Joomla includes many features that help with the task of securing applications and extensions built on it. You should always use these features if at all possible as they have been tried and tested by the many eyes of the developer community and any updates that might conceivably be required in the future will be automatically available whenever a Joomla update is applied. What follows is a description of best practice in using the Joomla API to ensure that your extensions are as secure as possible.

Getting data from the request

Starting with Joomla version 3.0, JInput should be used instead of JRequest.

All input originating from a user must be considered potentially dangerous and must be cleaned before being used. You should always use the Joomla JInput class to retrieve data from the request, rather than the raw $_GET, $_POST or $_REQUEST variables as the JInput methods apply input filtering by default. JInput deals with all aspects of the user request in a way that is independent of the request method used. It can also be used to retrieve cookie data and even server and environment variables. However, it is important to use the correct JInputmethod to ensure maximum security. It is very easy to just use the JInput->get method with default parameters and ignore the fact that in many cases it is possible to apply a more stringent requirement on user input.

It very important to understand that the JInput methods are not SQL-aware and further work is required to guard against SQL injection attacks.There is no default value that will be returned if no default is specified in the call theJInput->get. If no default is specified and the argument is not present in the request variable then it will return undefined.

Using JInput also obviates the need to pay attention to the setting of magic_quotes_gpc. JInput does the right thing, regardless of whether magic_quotes_gpc is on or off. Seehttp://php.net/manual/en/security.magicquotes.php for further information.

When considering user input you should think about the data type you are expecting to retrieve and apply the most stringent form of JInput that is applicable in each case. In particular, avoid the lazy approach of using JInput->get as this will return an array that may contain entries that you did not expect and although each of those entries will have been cleaned, it is often the case that additional filtering could have been applied to some individual arguments. For example, the get method treats all arguments as strings, whereas it may be possible to restrict some arguments to be integers.

The first three parameters of each of the JInput get methods are the same. Only the first parameter is mandatory. In general, the format is

    JFactory::getApplication->input-><data-source>->get<type>( <name>, <default> )

where

The following values for <data-source> are supported:

Notice that the default is REQUEST, which includes cookie data.

The following sections look at each of the data types in more detail.

Integer

The following will accept an integer. An integer can include a leading minus sign, but a plus sign is not permitted.

$integer = JFactory::getApplication->input->getInt( 'id' );

will return the value of the "id" argument from the request (which by default includes all GET, POST and COOKIE data). The default value is zero.

$integer = JFactory::getApplication->input->cookie->getInt( 'myId', 12 );

will return the value of the "myId" variable from a cookie, with a default value of 12.

Floating point number

A floating point number can include a leading minus sign, but not a plus sign. If the number includes a decimal point, then there must be at least one digit before the decimal point. For example,

$float = JFactory::getApplication->input->getFloat( 'price' );

will return the value of the 'price' argument from the request. The default is "0.0".

$float = JFactory::getApplication->input->post->getFloat( 'total', 100.00 );

will retrieve the value of the 'total' argument from a POST request (but not a GET), with a default value of 100.00.

Boolean value

Any non-zero value is regarded as being true; zero is false.

$boolean = JFactory::getApplication->input->getBool( 'show' );

will return false if the value of the 'show' argument in the request is zero, or 1 (true) if the argument is anything else. The default is false. Note that any string argument will result in a return value of true, so calling the above with a URL containing "?show=false" will actually return true!

$boolean = JFactory::getApplication->input->get->getBool( 'hide', true );

will retrieve the value of the 'hide' argument from a GET request (but not a POST), with a default value of true.

Word

A word is defined as being a string of alphabetic characters. The underscore character is permitted as part of a word.

$word = JFactory::getApplication->input->cookie->getWord( 'search-word' );

will retrieve the value of the 'search-word' argument from the request. The default is an empty string.

$word = JFactory::getApplication->input->cookie->getWord( 'keyword', '' );

will retrieve the value of the 'keyword' variable from a cookie, with the default being an empty string.

Command

A command is like a word but a wider range of characters is permitted. Allowed characters are: all alphanumeric characters, dot, dash (hyphen) and underscore.

$command = JFactory::getApplication->input->getCmd( 'option' );

will retrieve the value of the "option" argument from the request. The default value is an empty string.

$command = JFactory::getApplication->input->post->getCmd( 'controller', 'view' );

will retrieve the value of the "controller" argument from a POST request (but not a GET), with a default value of 'view'.

String

The string type allows a much wider range of input characters. It also takes an optional fourth argument specifying some additional mask options. See #Filter options for information on the available masks.

$string = JFactory::getApplication->input->getString( 'description' );

will retrieve the value of the "description" argument from the request. The default value is an empty string. The input will have whitespace removed from the left and right ends and any HTML tags will be removed.

$string = JFactory::getApplication->input->getString( 'text', '' );

will retrieve the value of the "text" argument from the request.. The default value is an empty string.

$string = JFactory::getApplication->input->getString( 'template', '<html />' );

will retrieve the value of the "template" argument from the request. The default value is '<html></html>'.

JSON String

$json = JFactory::getApplication->input->json->get( 'var_name' );

Generic and other data types

If the above methods do not meet your needs, there is a small number of additional filter types which you can use by calling the JInput->get method directly. The syntax is:

JFactory::getApplication->input->get( <name>, <default>, <type> );

where:

The first three arguments are the same as for the more specific methods described earlier. Only the first argument is mandatory.

Allowed values of the <type>, which is case-insensitive, are as follows:

Filter options

All input values can be filtered using JFilterInput->clean.

Filter an array of values.

$data = JFactory::getApplication()->input->post->get('data', array(), 'array');
$filter = JFilterInput::getInstance();
 
foreach ($data as $value)
{
	$array[] = $filter->clean($value, 'string');
}

For more filter types see JFilterInput source.

Options listed bellow available only in deprecated JRequest library. Allowed values of <options> are as follows (none of these are applied by default):

Masks can be combined by logically OR'ing them. If no filter options are specified, then by default, whitespace is trimmed and HTML is removed.

File uploads

Web servers already have a good deal of security around handling file uploads, but it is still necessary to take additional steps to ensure that file names and paths cannot be abused. A simplified form which requests a file to be uploaded looks like this:

<form action="index.php?option=com_mycomponent/form_handler.php"  method="post" enctype="multipart/form-data">
        <input type="file" name="Filedata" />
    <input type="submit" />
</form>

On clicking the submit button, the browser will upload the file in a POST request, passing control to Joomla which will call "components/com_mycomponent/form_handler.php". This will include code like the following. The variable $somepath must be set to some path where the web server has permission to create files.

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die( 'Restricted access' );
 
// Get the file data array from the request.
$file = JFactory::getApplication->input->get( 'Filedata', '', 'files', 'array' );
 
// Make the file name safe.
jimport('joomla.filesystem.file');
$file['name'] = JFile::makeSafe($file['name']);
 
// Move the uploaded file into a permanent location.
if (isset( $file['name'] )) {
 
    // Make sure that the full file path is safe.
    $filepath = JPath::clean( $somepath.'/'.strtolower( $file['name'] ) );
 
    // Move the uploaded file.
    JFile::upload( $file['tmp_name'], $filepath );
}

Saving a request variable into user state

Because setting a user state variable from a variable in the request is such a common operation, there is an API method to make the task easier. This is generally safe to use because it calls JInput->get to obtain the input from the request, but remember that none of the input filtering calls will protect against SQL injection attempts.

$app = JFactory::getApplication();
$app->getUserStateFromRequest( <key>, <name>, <default>, <type> );

where

For example, getting an integer variable called 'id' from the request with a default value of 0, then saving it into a session variable called 'myid' can be done like this:

$app = JFactory::getApplication();
$app->getUserStateFromRequest( 'myid', 'id, 0, 'int' );

instead of something like this:

$app = JFactory::getApplication();
$app->setUserState( 'myid', $app->input->getInt( 'id', 0 ) );

Constructing SQL queries

One of the most common forms of attack on web applications is SQL injection, where the aim of the attacker is to change a database query by exploiting a poorly filtered input variable. Injecting modified SQL statements into the database can damage data or reveal private information. It is important to ensure that when SQL statements are constructed, they are correctly escaped and quoted so that bad input data cannot result in a bad SQL statement. You cannot rely on the JInput methods to do this as they are not SQL-aware.

Secure integers and the rest of numeric values

With the MySQL database, numeric fields should not be quoted, so it is important that they be typecast instead. Failure to do this will leave your code vulnerable to an attacker inserting a string containing SQL data.

Depending on the type, numeric types are cast like this:

// For SQL data types: INT, INTEGER, TINYINT, SMALLINT, MEDIUMINT, BIGINT, YEAR
$query = 'SELECT * FROM #__table WHERE `id`=' . (int) $id;
 
// For SQL data types: FLOAT, DOUBLE
$query = 'SELECT * FROM #__table WHERE `id`=' . (float) $id;

It's a good idea to get into the habit of always typecasting integers like this even if the variable was previously obtained using [[Further information on SQL injection attacks can be found here: http://php.net/manual/en/security.database.sql-injection.php and here: JInput->getInt.

Secure strings

In the examples that follow it is assumed that $db is an instance of a Joomla database object. This can always be obtained from JFactory using

$db = JFactory::getDBO();

Strings should always be escaped before being used in an SQL statement. This is actually very simple as the JDatabase->quote method escapes everything for you. You can also use the JDatabase->escape method directly. The following statements are equivalent:

$query = 'SELECT * FROM #__table WHERE `field` = ' . $db->quote( $db->escape( $field ), false );
 
$query = 'SELECT * FROM #__table WHERE `field` = ' . $db->quote( $field );

Secure on search

Special attention should be paid to LIKE clauses which contain the % wildcard character as these require special escaping in order to avoid possible denial of service attacks. LIKE clauses can be handled like this:

// Construct the search term by escaping the user-supplied string and, if required, adding the % wildcard characters manually.
$search = '%' . $db->escape( $search, true ) . '%' );
 
// Construct the SQL query, being careful to suppress the default behaviour of Quote so as to prevent double-escaping.
$query = 'SELECT * FROM #__table WHERE `field` LIKE ' . $db->quote( $search, false );

Secure dates

If data is to be entered into a datetime column then you can use the Joomla API to ensure a valid date format:

$date = JFactory::getDate( $mydate );
$query = 'UPDATE #__table SET `date` = ' . $db->quote( $date->toMySQL(), false );

Note that it is necessary to suppress database escaping as legitimate dates may contain characters that should not be escaped.

Secure field names

In the comparatively rare case where a field name is a variable, that should also be quoted using an API call:

$query = 'SELECT * FROM #__table WHERE ' . $db->quoteName( $field-name ) . '=' . $db->quote( $field-value );

Secure arrays of integers

When you have an array of ids, typically used for IN() queries, you have to sanitise it also with JArrayHelper::toInteger($cid); before imploding:

...
JArrayHelper::toInteger($catId);
$query->where($db->quoteName('x.category_id') . ' IN (' . implode(',', $catId) . ')');

Short aliases of Quote and QuoteName

Shorter alternatives to the quote methods may also be used. The following statements are equivalent:

$query = 'SELECT * FROM #__table WHERE ' . $db->quoteName( $field-name ) . '=' . $db->quote( $field-value );
$query = 'SELECT * FROM #__table WHERE ' . $db->qn( $field-name ) . '=' . $db->q( $field-value );

Securing forms

Apart from cleaning input variables as described above, you can also implement a simple technique which makes it more difficult for a cross-site request forgery attack (CSRF) to succeed. This involves adding a randomly-generated unique token to the form which is checked against a copy of the token held in the user's session. By checking that the submitted token matches the one contained in the stored session, it is possible to tie a rendered form to the request variables presented.

In POST forms you should add a hidden token field using:

echo JHTML::_( 'form.token' );

This outputs the token as a hidden form field looking like this:

<input type="hidden" name="8cb24ae69ffd7828ccecbcf06056e6fc" value="1" />

and places a copy of the token into the user's session, for later checking.

If you need to add the token to a URL rather than a form then you can use something like this:

echo JRoute::_( 'index.php?option=com_mycomponent&' . JSession::getFormToken() . '=1' );

In the most common scenario, you will want to check the token following a POST to the form handler. This can be done by adding this line of code to form handler:

JSession::checkToken() or die( JText::_( 'Invalid Token' ) );

If you need to pass the token in a GET request then you can check it like this:

JSession::checkToken( 'get' ) or die( JText::_( 'Invalid Token' ) );

In both cases the code will die if the token is omitted from the request, or the submitted token does not match the session token. If the token is correct but has expired, then JSession::checkToken will automatically redirect to the site front page.

Cleaning filesystem paths

If there is any possibility that a filesystem path might be constructed using data that originated from user input, then the path must be cleaned and checked before being used. This can be done quite simply like this:

JPath::check( $path );

This will raise an error and terminate Joomla if the path contains a ".." or leads to a location outside the Joomla root directory. If you want to deal with the error yourself without terminating the application, then you can use code like this:

$path = JPath::clean( $path );
if (strpos( $path, JPath::clean( JPATH_ROOT ) ) !== 0) {
    // Handle the error here.
}

The JPath:clean method can be used in your own code too. It merely removes leading and trailing whitespace and replace double slashes and backslashes with the standard directory separator.

Cleaning filesystem file names

As with filesystem paths, if there is any possibility that a file name might be constructed using user-originated data, then the file name must be cleaned and checked before use. This can be done like this:

jimport('joomla.filesystem.file');
$clean = JFile::makeSafe( $unclean );

This method removes sequences of two or more "." characters and any character that is not alphabetic, numeric or a dot, dash or underscore character. If there is a leading dot then that is removed too.