File Dialog – Restricted Paths

Common User Interface

Task ID(s)

111008

Category	Specification Affects

Abstract

OpenOffice.org features an own implementation for a file and folder picker dialog. This dialog is used for all tasks where the user has to browse for a file (such as Insert|Graphics|From File, or opening/saving files, etc) or a directory.

With the feature which is described here, it's possible to restrict the operations which can be done with this dialog to a certain list of folders and their descendants.

i-Team

Specification Owner	Frank Schönheit	fs@openoffice.org
Marketing (MA)		
User Experience (UX)		
Development (DEV)	Frank Schönheit	fs@openoffice.org
Quality Assurance (QA)	Thorsten Martens	tm@openoffice.org
Documentation (DOC)		

Specification Reviews

Version	Reviewer	Comment
Reviewed by UX <Date>	<Name>	<Comment>
UI String Review <Date>		
Reviewed by QA <Date>		
Reviewed by DOC <Date>		

Document History

Version	Author	Comment
Draft 07/31/03	Frank Schönheit	initial revision
Draft 09/04/03	Frank Schönheit	minor pre-publishing changes
Final <Date>		

Contents

Glossary	1

References	1

1	Motivation	1

2	Goals	1

3	Dependencies	1

3.1	Technical Dependencies / Requirements	1

4	Detailed Specification	1

Browsing the File Hierarchy	2

AutoCompletion in the FileName Field	2

"Default Directory" Button	2

Declaring the Permitted Folders	3

Links	3

Standard Working Directory	3

Unrestricted Dialog	3

4.1	Error Conditions	3

5	Future Tasks	4

6	Legal Issues	4

7	Notes	4

Glossary

Term	Description
file system object	a file or a folder in the file system hierarchy of the user's machine
open a file	In the scope of this document, we refer to every operation which, by use of the file dialog, lets the user select a file for further processing (such as inserting a graphics from a file, opening a file for editing/reading, inserting part documents into master documents, etc.) as "open a file".
current folder	at a given time, the folder which is currently being displayed in the file dialog
file operation	a operation in the file system, done using the internal file dialog of OpenOffice.org. In particular: save a file open a file in case the file dialog acts as folder picker: Select the current folder by pressing the "Select" button.
permitted folder	A folder in the file system which the user should access without any restriction.

References

n/a

Motivation

There was a demand from users of OpenOffice.org for this feature.

Goals

Using OpenOffice.org's internal file dialog, the user will not be able to browse the complete folder hierarchy on his/her machine, but only a set of restricted paths. Every file operation outside these restricted paths will not be possible.

Dependencies

Technical Dependencies / Requirements

n/a

Detailed Specification

In the course of this document, we will assume a machine with the following file and folder structure (shown in parts, imagine additional structures at will):

/ /

+--- opt /opt

+--- home /home

| +--- user /home/user

| | +--- fileOne /home/user/fileOne

| | +--- fileTwo /home/user/fileTwo

| | +--- first /home/user/first

| | | +--- fileFirst /home/user/first/fileFirst

| | +--- second /home/user/second

| +--- user2 /home/user2

| +--- fileThree /home/user2/fileThree

+--- tmp /tmp

+--- floppy /floppy

+--- etc /etc

Browsing the File Hierarchy

Using means which are explained below, the user or his/her administrator can define a list of folders which should restrict the perception for the user. In particular, the list of permitted folders spans a virtual file structure, and the file dialog will only operate on this virtual structure.

As an example, let's assume that there are two permitted folders, "/home/user" and "/floppy". In this case, the virtual file system spanned by these folders is as follows:

/ /

+--- home /home

| +--- user /home/user

| +--- fileOne /home/user/fileOne

| +--- fileTwo /home/user/fileTwo

| +--- first /home/user/first

| | +--- fileFirst /home/user/first/fileFirst

| +--- second /home/user/second

+--- floppy /floppy

Using the file dialog, the user will never encounter a file system object which is not part of this virtual hierarchy.

In particular, the user will be able to browse to places which are not below a permitted folder, but there s/he will only see file system objects which lead to a permitted folder.
E.g., in the example above, the user will be able to browse to "/", but will not see any folders or files in this location except "home" and "floppy", in particular "opt", "tmp" and "etc" will not be visible.

Browsing within or below a permitted folder will not behave different from browsing in the real file hierarchy (instead of the virtual one).

AutoCompletion in the FileName Field

The automatic completion of the user input, which takes place in the field used to input the name of file system objects, will also work on the virtual file hierarchy only. Neither in the drop down list of this field, nor in the automatically completed text in the input box, the user will encounter file system objects which do not belong to the virtual file hierarchy as explained above.

"Default Directory" Button

The button to quickly browse to the default directory, as set up in the configuration, will be extended. It will be a drop-down button (equivalent to the "Up One Level" button), which when pressed opens a list with all permitted folders. Choosing one entry from this list immediately browses to this folder.

The drop down menu with the list of permitted folders will be opened upon a longer click only (the usual delay for drop down buttons within OpenOffice.org). Upon a single click, it will behave as before, and browse to the default directory.

Declaring the Permitted Folders

The list of permitted folders is taken from an environment variable called "RestrictedPath". This path contains a separated list of folders which are permitted. Separation character is ';' (semicolon) on Windows, and ':' (colon) on all other systems.

When such an environment variable is set, and not empty, it will be analyzed for it's single components. Every component is interpreted as either file system path (such as "/home/user"), or alternatively as URL (such as http://intranet/documents). Especially the latter enables corporations to e.g. include a WebDAV directory on an intranet server in the list of permitted folders.

Empty components in this list are ignored.

Links

On systems which support links in the file system, these links will be handled as if they were normal file system objects. This means if a permitted folder (or a descendant folder) contains a link which points to a file system object which is not part of the virtual hierarchy, this link is not masked out. This is consistent with the behaviour of the operating system shell: The linked object behaves as if it's really placed where the link resides.

Standard Working Directory

Upon starting OpenOffice.org, the working directory (as to be found in Tools|Options|General|Path) will be set to the first element of the list of permitted folders. This setting is also persistent, means it lasts longer than the office session itself.

Unrestricted Dialog

If there are no restrictions in place, i.e. if the environment variable is not set, or does not contain any non-empty components, the file dialog will, in all aspects, behave as usual, means it will be limited by the operating system restrictions only. In particular, the AutoCompletion will work as usual, and the "Default Directory" button will not act as drop-down button.

Error Conditions

Condition: One of the following operations is attempted by the user, by entering a the path to a file system object directly into the dialog's file name input field:

Open a file which does not reside below a permitted folder.
In our sample structure, this would apply to opening "/home/user2/fileThree".

Save a file to a location which does not reside below a permitted folder.
In our sample structure, this would apply to saving a file as "/tmp/removeme.sxw", or as "/home/file.sxw".

When in folder picker mode, select a directory which does not reside below a permitted folder, nor is a permitted folder itself, nor is an ancestor of a permitted folder. In our sample structure, this would apply to selecting "/etc", but not to selecting "/home".

Reaction: An error message will be shown telling the user that the access to the file system object in question is denied. This error message is the same as when accessing an object which is restricted by the operating system.

Condition: The file dialog is initialized with a directory which is not part of the virtual file system hierarchy.
This may happen when the user opens a document from a disallowed location (e.g. "/home/user2/fileThree") bypassing the dialog (e.g. by specifying it at the comment line), and then tries to save the file under a different name. In an unrestricted dialog, the folder where the file resides ("/home/user2") would be made the current folder. In an restricted dialog, this is not possible, because the folder is not part of the virtual file system.
Reaction: The first element of the list of permitted folders is made the current folder of the dialog.

Future Tasks

There should be a configuration entry which specifies the set of permitted folders.

Legal Issues

n/a

Notes

n/a

File Dialog – Restricted Paths

Page 4

http://ui.openoffice.org/specification/FileDialog_RestrictedPaths.sxw

2003-07-31T11:22:09