Home

c't SESAM Server

Sync server for c't SESAM

c't SESAM Server is a data store for c't SESAM. It's supposed to be installed on a web server and used by only you or a small community (your family, close friends).

The web server must support PHP 5.x (or newer) with SQLite module activated.

Getting Started

Your personal instance of ctSESAM-server is easy to set up:

• Clone the repository.
• Copy the project files into a directory accessible by your webserver. The following assumes that all files are contained in the directory D:/Developer/xampp/htdocs/ctSESAM-server and that this directory can be accessed by a client via the URL https://localhost/ctSESAM-server. Reminder: You should prefer to use HTTPS rather than unencrypted HTTP because ctSESAM-server recognizes its users via HTTP basic access authentication by which credentials are transferred in an unsafe way. HTTPS requires the setup of certificate chain.
• For HTTP basic access authentication you should protect the just created directory by placing an .htaccess file there (Apache users!) or doing something else adequate for your preferred web server.
• Check your configuration by calling the URL in your favorite web browser: You should see the message "This page is intentionally left blank.".
• The ctSESAM-server configuration is read from the file config.php. Copy config-default.php to config.php to set it up.
• ctSESAM-server uses an SQLite 3 database to store data. Set $config['db_path]' to the path of the SQLite database file and $config['db_name'] to its name. The configured directory must be writable by your web server. By default path and name point to '/var/www/sqlite/ctSESAM-server.sqlite.
• Call https://localhost/ctSESAM-server/install.php to create the database.

ctSESAM-server is now ready for action.

Data Storage

The SQLite 3 database contains a single table with the following layout:

Field	Type	Description
userid	TEXT	associated user name (primary key)
data	BLOB	ctSESAM data

Data Specs

Converting the raw data to the JSON object literal must lead to the following structure whereby <string>, <boolean> and so on describe the types of the actual values:

{
  'domain': <string>,
  'url': <string>,
  'username': <string>,
  'legacyPassword': <string>,
  'notes': <string>,
  'iterations': <integer>,
  'salt': <salt>,
  'cDate': <string>,
  'mDate': <string>,
  'usedCharacters': <string>,
  'deleted': <boolean>,
  'extras': <string>,
  'files': <map of strings>,
  'tags': <string>,
  'passwordTemplate': <string>
}

The field domain contains the domain the rest of the data refers to.

The field username contains the user's name used for the domain.

You may use the field legacyPassword to store a password if the domain does not allow to set or change a once given password.

The field notes can contain arbitrary text.

The field iterations contains the number of iterations used for PBKDF2.

The field salt contains the salt used for PBKDF2. The salt must be a Base64 encoded byte sequence.

The fields cDate and mDate contain dates in ISO 8601 format (e.g. "2015-05-28T14:07:12"), whereby cDate resembles the date and time when the data set was created, and mDate when it was last modified.

If deleted is true the client knows that it can delete its local instance of the domain's data and all other fields except domain can be empty or missing.

The field passwordTemplate can contain a template for the password. It will be used not before c't SESAM v 2.1. If it's set, it must be formatted as follows: <complexity>;<templatestring>, whereby <complexity> represents a number between 0 and 6 (inclusively) and <templatestring> the template string, i.e. any character sequence consisting of the characters 'a', 'A', 'n', 'o' and 'x'. The character 'a' represents a lowercase character, 'A' an uppercase character, 'n' a digit, 'o' any character contained in the field extra, and 'x' any character contained in the field usedCharacters. If passwordTemplate is set the value of length will be ignored, because the length of <templatestring> implicates this value.

The field tags can contain a list of comma-separated tags. This field is optional and currently not used by c't SESAM.

The field files can contain map of base64-encoded byte arrays, whereas the key denotes the file name and the value contains the base64-encoded contents of the file.

Communication Protocols

In General

All data sent from the client to server must be sent via HTTP(S)-POST with MIME type "application/x-www-form-urlencoded". The request must contain a HTTP basic authorization header like Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== in which the last string portion represents the base64 encoded concatenation of username:password.

The server extracts username from the header and uses it to reference the table field userid which is used to select the entry of that user. password is ignored and can be empty unless the header is actually used for HTTP Basic authorization.

Read All Domain Data

A client must access ajax/read.php to read all user's data.

The POST data shall be empty.

The server responds with JSON encoded data like:

{
  'result': <string>,
  'status': <string>,
  'error': <string>
}

The field result contains the encrypted base64 encoded domain settings of username, extended by the field status, and, if applicable, error.

status contains the string "ok" if no errors occurred. Otherwise is contains "error" and the field error is set to a descriptive error message. In the latter case result may be empty.

Create/Update Domain Data

A client must access ajax/write.php to create a new data set for a user or updates an existing one.

The POST data must be x-www-form-urlencoded and contain the single field data with the encrypted domain settings of the user given in the HTTP Basic Authentication string.

If the server finds an entry for the given user, it updates the stored data with the contents of data. If not, a new entry is created.

The server responds with JSON encoded data like:

{
  'rowsaffected': <int>,
  'status': <string>,
  'error': <string>,
  'result': <string>
}