Next: 20. Bounce management Up: Sympa Mailing Lists Management Software version Previous: 18. List configuration parameters Contents Index
Subsections

- 19.1 The three kind of operations on a document
- 19.2 The description file
  - 19.2.1 Structure of description files
- 19.3 The predefined authorization scenarios
  - 19.3.1 The public scenario
  - 19.3.2 The private scenario
  - 19.3.3 The scenario owner
  - 19.3.4 The scenario editor
- 19.4 Access control
  - 19.4.1 Listmaster and privileged owners
  - 19.4.2 Special case of the `shared` directory
  - 19.4.3 General case
- 19.5 Shared document actions
- 19.6 Template files
  - 19.6.1 d_read.tt2
  - 19.6.2 d_editfile.tt2
  - 19.6.3 d_control.tt2
  - 19.6.4 d_upload.tt2
  - 19.6.5 d_properties.tt2

#
19. Shared documents

Shared documents are documents that different users can manipulate on-line via the web interface of Sympa, provided that the are authorized to do so. A shared space is associated with a list, and users of the list can upload, download, delete, etc, documents in the shared space.

WWSympa shared web features are fairly rudimentary. It is not our aim to provide a sophisticated tool for web publishing, such as are provided by products like Rearsite. It is nevertheless very useful to be able to define privilege on web documents in relation to list attributes such as subscribers, list owners, or list editors.

All file and directory names are lowercased by Sympa. It is consequently impossible to create two different documents whose names differ only in their case. The reason Sympa does this is to allow correct URL links even when using an HTML document generator (typically Powerpoint) which uses random case for file names!

In order to have better control over the documents and to enforce security in the shared space, each document is linked to a set of specific control information : its access rights.

A list's shared documents are stored in the `/usr/local/sympa-os/expl/mylist/shared` directory.

This chapter describes how the shared documents are managed, especially as regards their access rights. We shall see :

- the kind of operations which can be performed on shared documents

- access rights management

- access rights control specifications

- actions on shared documents

- template files

#
19.1 The three kind of operations on a document

Where shared documents are concerned, there are three kinds of operation which have the same constraints relating to access control :

- The read operation :
  - If applied on a directory, opens it and lists its contents (only those sub-documents the user is authorized to ``see'').
  - If applied on a file, downloads it, and in the case of a viewable file (text/plain, text/html, or image), displays it.
- The edit operation allows :
  - Subdirectory creation
  - File uploading
  - File unzipping
  - Description of a document (title and basic information)
  - On-line editing of a text file
  - Document (file or directory) removal. If on a directory, it must be empty.
  These different edit actions are equivalent as regards access rights. Users who are authorized to edit a directory can create a subdirectory or upload a file to it, as well as describe or delete it. Users authorized to edit a file can edit it on-line, describe it, replace or remove it.
- The control operation :
  The control operation is directly linked to the notion of access rights. If we wish shared documents to be secure, we have to control the access to them. Not everybody must be authorized to do everything to them. Consequently, each document has specific access rights for reading and editing. Performing a control action on a document involves changing its Read/Edit rights.
  The control operation has more restrictive access rights than the other two operations. Only the owner of a document, the privileged owner of the list and the listmaster have control rights on a document. Another possible control action on a document is therefore specifying who owns it.

#
19.2 The description file

The information (title, owner, access rights...) relative to each document must be stored, and so each shared document is linked to a special file called a description file, whose name includes the `.desc` prefix.

The description file of a directory having the path `mydirectory/mysubdirectory` has the path `mydirectory/mysubdirectory/.desc` . The description file of a file having the path `mydirectory/mysubdirectory/myfile.myextension` has the path `mydirectory/mysubdirectory/.desc.myfile.myextension` .

## 19.2.1 Structure of description files

The structure of a document (file or directory) description file is given below. You should never have to edit a description file.

    title
      <description of the file in a few words>

    creation
      email        <e-mail of the owner of the document>
      date_epoch   <date_epoch of the creation of the document>

    access
     read <access rights for read>
     edit <access rights for edit>

The following example is for a document that subscribers can read, but which only the owner of the document and the owner of the list can edit.

    title
      module C++ which uses the class List

    creation
      email foo@some.domain.com
      date_epoch 998698638

    access
     read  private
     edit  owner

#
19.3 The predefined authorization scenarios

## 19.3.1 The public scenario

The public scenario is the most permissive scenario. It enables anyone (including unknown users) to perform the corresponding action.

## 19.3.2 The private scenario

The private scenario is the basic scenario for a shared space. Every subscriber of the list is authorized to perform the corresponding action. The private scenario is the default read scenario for `shared` when this shared space is created. This can be modified by editing the list configuration file.

## 19.3.3 The scenario owner

The scenario owner is the most restrictive scenario for a shared space. Only the listmaster, list owners and the owner of the document (or those of a parent document) are allowed to perform the corresponding action. The owner scenario is the default scenario for editing.

## 19.3.4 The scenario editor

The scenario editor is for a moderated shared space for editing. Every suscriber of the list is allowed to editing a document. But this document will have to be installed or rejected by the editor of the list. Documents awaiting for moderation are visible by their author and the editor(s) of the list in the shared space. The editor has also an interface with all documents awaiting. When there is a new document, the editor is notiied and when the document is installed, the author is notiied too. In case of reject, the editor can notify the author or not.

#
19.4 Access control

Access control is an important operation performed every time a document within the shared space is accessed.

The access control relative to a document in the hierarchy involves an iterative operation on all its parent directories.

## 19.4.1 Listmaster and privileged owners

The listmaster and privileged list owners are special users in the shared web. They are allowed to perform every action on every document in the shared space. This privilege enables control over the shared space to be maintained. It is impossible to prevent the listmaster and privileged owners from performing whatever action they please on any document in the shared space.

##
19.4.2 Special case of the `shared` directory

In order to allow access to a root directory to be more restrictive than that of its subdirectories, the `shared` directory (root directory) is a special case as regards access control. The access rights for read and edit are those specified in the list configuration file. Control of the root directory is specific. Only those users authorized to edit a list's configuration may change access rights on its `shared` directory.

## 19.4.3 General case

`mydirectory/mysubdirectory/myfile` is an arbitrary document in the shared space, but not in the root directory. A user X wishes to perform one of the three operations (read, edit, control) on this document. The access control will proceed as follows :

- Read operation
  To be authorized to perform a read action on `mydirectory/mysubdirectory/myfile`, X must be authorized to read every document making up the path; in other words, she must be allowed to read `myfile` (the authorization scenario of the description file of `myfile` must return do_it for user X), and the same goes for `mysubdirectory` and `mydirectory`).
  In addition, given that the owner of a document or one of its parent directories is allowed to perform all actions on that document, `mydirectory/mysubdirectory/myfile` may also have read operations performed on it by the owners of `myfile`, `mysubdirectory`, and `mydirectory`.

  This can be schematized as follows :

      	X can read <a/b/c>

      	if

      	(X can read <c>
      	AND X can read <b>
      	AND X can read <a>)

      	OR

      	(X owner of <c>
      	OR X owner of <b>
      	OR X owner of <a>)

- Edit operation
  The access algorithm for edit is identical to the algorithm for read :

      	X can edit <a/b/c>

      	if

      	(X can edit <c>
      	AND X can edit <b>
      	AND X can edit <a>)

      	OR

      	(X owner of <c>
      	OR X owner of <b>
      	OR X owner of <a>)

- Control operation
  The access control which precedes a control action (change rights or set the owner of a document) is much more restrictive. Only the owner of a document or the owners of a parent document may perform a control action :

      	X can control <a/b/c>

      	if

      	(X owner of <c>
      	OR X owner of <b>
      	OR X owner of <a>)

# 19.5 Shared document actions

The shared web feature has called for some new actions.

- action D_ADMIN
  Create the shared web, close it or restore it. The d_admin action is accessible from a list's admin page.
- action D_READ
  Reads the document after read access control. If a folder, lists all the subdocuments that can be read. If a file, displays it if it is viewable, else downloads it to disk. If the document to be read contains a file named `index.html` or `index.htm`, and if the user has no permissions other than read on all contained subdocuments, the read action will consist in displaying the index. The d_read action is accessible from a list's info page.
- action D_CREATE_DIR
  Creates a new subdirectory in a directory that can be edited without moderation. The creator is the owner of the directory. The access rights are those of the parent directory.
- action D_DESCRIBE
  Describes a document that can be edited.
- action D_DELETE
  Deletes a document after edit access control. If applied to a folder, it has to be empty.
- action D_UPLOAD
  Uploads a file into a directory that can be edited.
- action D_UNZIP
  Unzip a file into a directory that can be edited without moderation. The whole file hierarchy contained in the zip file is installed into the directory.
- action D_OVERWRITE
  Overwrites a file if it can be edited. The new owner of the file is the one who has done the overwriting operation.
- actions D_EDIT_FILE and D_SAVE_FILE
  Edits a file and saves it after edit access control. The new owner of the file is the one who has done the saving operation.
- action D_CHANGE_ACCESS
  Changes the access rights of a document (read or edit), provided that control of this document is authorized.
- action D_SET_OWNER
  Changes the owner of a directory, provided that control of this document is authorized. The directory must be empty. The new owner can be anyone, but authentication is necessary before any action may be performed on the document.

# 19.6 Template files

The following template files have been created for the shared web:

## 19.6.1 d_read.tt2

The default page for reading a document. If for a file, displays it (if viewable) or downloads it. If for a directory, displays all readable subdocuments, each of which will feature buttons corresponding to the different actions this subdocument allows. If the directory is editable, displays buttons to describe it or upload a file to it. If the directory is editable without moderation, it displays button to create a new subdirector or to upload a zip file in order to install a file hierarchy. If access to the document is editable, displays a button to edit the access to it.

## 19.6.2 d_editfile.tt2

The page used to edit a file. If for a text file, allows it to be edited on-line. This page also enables another file to be substituted in its place.

## 19.6.3 d_control.tt2

The page to edit the access rights and the owner of a document.

## 19.6.4 d_upload.tt2

This page to upload a file is only used when the name of the file already exists.

## 19.6.5 d_properties.tt2

This page is used to edit description file and to rename it.

Next: 20. Bounce management Up: Sympa Mailing Lists Management Software version Previous: 18. List configuration parameters Contents Index