diff --git modules/filter/filter.api.php modules/filter/filter.api.php index 5e20ed2..c0038ce 100644 --- modules/filter/filter.api.php +++ modules/filter/filter.api.php @@ -40,6 +40,10 @@ * content before the actual filtering happens. * - 'process callback': The name the function that performs the actual * filtering. + * - When a text format is checked to determine if it is configured securely, + * the following properties may be used: + * - 'security callback': The name of a function that determines whether the + * filter allows new exploits or prevents existing ones. * * Filtering is a two-step process. First, the content is 'prepared' by calling * the 'prepare callback' function for every filter. The purpose of the 'prepare @@ -64,6 +68,14 @@ * format is an entire filter setup: which filters to enable, in what order * and with what settings. * + * Different filters can introduce or remove security vulnerabilities in the + * text formats that contain them, depending on how they are configured. + * Filters whose presence in a text format can have implications for security + * should therefore use the 'security callback' function to provide information + * about whether they are configured securely. The filtering system will + * collect this information and use it to automatically determine whether the + * text format as a whole is secure. + * * Filters that require settings should provide the form controls to configure * the settings in a form builder function, specified in 'settings callback'. * The filter system stores the settings in the database per text format. @@ -122,6 +134,91 @@ * - $format: The format object of the text to be filtered. * - $long: Boolean whether to return long or short filter guidelines. * + * 'security callback' is invoked with the following parameters: + * - $filter: An object representing the filter within the text format that is + * being checked. The most important property is $filter->settings, which + * contains an array of settings for this filter as it is configured within + * the current text format. The security callback function should inspect + * these settings if they are relevant for determining when the filter is + * configured securely. + * + * - If the filter opens up a new exploit in a previously safe text format, + * or + * - If the filter could have specifically prevented an exploit if it had + * been configured in a different way. + * The callback retuns an array keyed by the two categories in which + * potential vulnerabilities exists, either 'html' or 'exec'. By + * far the most common category is 'html', which + * represents any vulnerability that occurs when the web browser processes + * the content as HTML (for example, cross-site scripting); this includes + * both HTML itself as well as other languages (such as JavaScript) that can + * be included in HTML. A filter which needs to output a warning message + * about an HTML-related vulnerability would therefore use code like the + * following: + * @code + * return array('html' => array( + * 'type' => FILTER_EXPLOT_CREATES, + * 'warning' => t('A message explaining the vulnerability.') + * )); + * @endcode + * Although HTML-related exploits are by far the most common category, others + * are possible for certain types of unusual filters. For example, the PHP + * module in Drupal core uses the 'exec' category to indicate that the PHP + * filter which it provides contains an inherent vulnerability since content + * is executed as PHP code on the server; this vulnerability represents a separate risk that is independent + * from any HTML-related vulnerabilities, and can not be undone by a later filter. + * In this case, the relevant code is therefore ('type' is optional since it always FILTER_EXPLOT_CREATES): + * @code + * return array('exec' => array( + * 'type' => FILTER_EXPLOT_CREATES, + * 'warning' => t('A message explaining the vulnerability.') + * )); + * @endcode + * Similarly, a hypothetical filter that took the content passed in to it and + * executed it as Perl code by running a local program on the web server + * would use the same format for its warning. + * + * The return value of the 'security callback' function is an optional array + * representing the effect of the filter on each category described above. The + * constant FILTER_EXPLOIT_PREVENTS should be used if the filter prevents + * security exploits by sanitizing previously-unsafe content; for example, a + * filter that escapes HTML would return: + * @code + * array('html' => FILTER_EXPLOIT_PREVENTS). + * @endcode + * The constant FILTER_EXPLOIT_ALLOWS should be used if the filter allows a new + * security exploit, even if the content passed in to the filter was previously + * sanitized. For example, a filter that evaluates PHP code would return: + * @code + * array('php' => FILTER_EXPLOIT_ALLOWS). + * @endcode + * Similarly, a filter that processes a certain kind of markup language and + * therefore transforms safe text, such as "[script]", into unsafe HTML tags, + * such as '