From aefecf29658d4f982361a57d9778d1753eb65b0a Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Mon, 21 Jun 2010 06:34:11 +0000
Subject: [PATCH] MINOR Documentation

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/branches/2.4@106804 467b73ca-7a2a-4603-9d3b-597d59a354a9
---
 filesystem/File.php   | 11 +++++++----
 filesystem/Upload.php | 19 +++++++++++++++++--
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/filesystem/File.php b/filesystem/File.php
index c3d8fa252..d851a9a57 100755
--- a/filesystem/File.php
+++ b/filesystem/File.php
@@ -5,6 +5,10 @@
  * looks at the db object to gather information about a file such as URL
  * It then uses this for all processing functions (like image manipulation).
  * 
+ * Caution: It is recommended to disable any script execution in the "assets/"
+ * directory in the webserver configuration, to reduce the risk of exploits.
+ * See http://doc.silverstripe.org/secure-development#filesystem
+ * 
  * @package sapphire
  * @subpackage filesystem
  */
@@ -44,8 +48,7 @@ class File extends DataObject {
 	);
 	
 	/**
-	 * @see Upload->allowedExtensions
-	 * @var array
+	 * @var array List of allowed file extensions, enforced through {@link validate()}.
 	 */
 	public static $allowed_extensions = array(
 		'','html','htm','xhtml','js','css',
@@ -59,8 +62,8 @@ class File extends DataObject {
 	);
 	
 	/**
-	 * If this is true, then restrictions set in $allowed_max_file_size and
-	 * $allowed_extensions will be applied to users with admin privileges as
+	 * @var If this is true, then restrictions set in {@link $allowed_max_file_size} and
+	 * {@link $allowed_extensions} will be applied to users with admin privileges as
 	 * well.
 	 */
 	public static $apply_restrictions_to_admin = true;
diff --git a/filesystem/Upload.php b/filesystem/Upload.php
index 36f90558f..4b75aa6f3 100644
--- a/filesystem/Upload.php
+++ b/filesystem/Upload.php
@@ -5,6 +5,15 @@
  * and either creates a new or uses an existing File-object
  * for syncing with the database.
  * 
+ * <b>Validation</b>
+ * 
+ * By default, a user can upload files without extension limitations,
+ * which can be a security risk if the webserver is not properly secured.
+ * Use {@link setAllowedExtensions()} to limit this list,
+ * and ensure the "assets/" directory does not execute scripts
+ * (see http://doc.silverstripe.org/secure-development#filesystem).
+ * {@link File::$allowed_extensions} provides a good start for a list of "safe" extensions.
+ * 
  * @package sapphire
  * @subpackage filesystem
  * 
@@ -409,7 +418,13 @@ class Upload_Validator {
 	}
 	
 	/**
-	 * @param array $rules
+	 * Limit allowed file extensions. Empty by default, allowing all extensions.
+	 * To allow files without an extension, use an empty string.
+	 * See {@link File::$allowed_extensions} to get a good standard set of
+	 * extensions that are typically not harmful in a webserver context.
+	 * See {@link setAllowedMaxFileSize()} to limit file size by extension.
+	 * 
+	 * @param array $rules List of extensions
 	 */
 	public function setAllowedExtensions($rules) {
 		if(!is_array($rules)) return false;
@@ -423,7 +438,7 @@ class Upload_Validator {
 	/**
 	 * Determines if the bytesize of an uploaded
 	 * file is valid - can be defined on an
-	 * extension-by-extension basis in {$allowedMaxFileSize}
+	 * extension-by-extension basis in {@link $allowedMaxFileSize}
 	 *
 	 * @return boolean
 	 */