Chapter 16: Storing Authentication Data

After a user has been granted access by the authentication feature, RealServer can check to see whether he or she has special permissions for viewing specific presentations or directories of presentations. You can use this information for applications such as pay-per-view. Working with the authentication feature, permission information is stored in a separate database. This chapter describes the data storage methods which can be used with the authentication feature.

Overview

To authenticate visitors, the RealServer stores user IDs and passwords or client IDs, and their associated access permission information. When a client tries to access a clip, the RealServer looks up this information to see whether the client or visitor is authorized to view the clip. The information can be stored in either a series of text files or in a database. Templates for common databases are installed during installation.

This section describes the methods for storing user name and password data. Templates for common databases are created during installation, that correspond to the database methods listed in "Creating a New Database".

Text file storage-this method uses a combination of directory structure and text files to achieve a sensible data storage method. It is the default method. See "Using Text Files for Authentication Data" for details.
Database templates-the supplied templates use a similar structure to the text file method, in a more familiar database format. Refer to "Using a Database for Authentication Data" for more information.

Using Text Files for Authentication Data

The default configuration uses the text file storage method to provide storage for all three default realms.

The following directories contain the text files which store data. The center letter indicates the authentication protocol: r is for RN5, b is for Basic.

Supplied Data Storage Directories
Directory Name	Data Storage for the following type of information
`enc_r_db`	Encoder User Authentication
`adm_b_db`	RealSystem Administrator User Authentication
`con_r_db`	Content Authentication

The contents of the directories are given in the table below.:

Text File Storage Directory Structure
Directory	Contents	File or Directory Description
Main directory (`con_r_db, enc_r,_db,` or `_adm_b_db`)	`ppvbasic.txt`	The text file indicates to RealServer that this is the storage area for the list of authenticated names.
`users`	(initially blank)	Files in this directory list the clips and permission types.
`guids`	(initially blank)	For player validation, files connect the clientID with a user name.
`logs`	`reglog.txt accesslog.txt`	See below for a description of these files.
`redirect`	(initially blank)	For player validation, files contain an URL to which to send the client if redirection is necessary.

The actual data storage text files do not exist when RealServer is first installed. They are created when authentication is in use and secure content is first requested. When RealServer creates the file structure, it creates the ppvbasic.txt file. The second and subsequent times you start the RealServer, the RealServer looks for this file. If the file does not exist, it recreates the directory structure.

Warning
Do not delete the ppvbasic.txt file! If you delete the ppvbasic.txt file, RealServer will rewrite the directories and will erase their prior content.

	Warning
Do not delete the `ppvbasic.txt` file! If you delete the `ppvbasic.txt` file, RealServer will rewrite the directories and will erase their prior content.

Users Directory

The files in this directory are named username, where username is the user name. This directory contains one file per registered user.

The first line of each file has the following format and is different than subsequent lines in the file:


password;uuid;uuid_writeable

where:


password	When user authentication is in use, this stores the password. Otherwise shows an asterisk (*). Note: Passwords are encrypted. See "Changing RealSystem 5.0 Authentication Passwords".
`uuid`	In player validation, stores playerID. In user authentication, an asterisk (*) appears in this field.
`uuid_writeable`	A flag set and used by RealServer: 0 playerID is in database 1 record created, but playerID is not yet registered

The second and subsequent lines of each file have the following form (for further detail on allowable values in each field, see database structure later in this chapter):


url;url_type;permission_type;expires;debitted_time


`url`	URL of secure directory or clip.
`url_type`	Whether URL is directory or clip: `0` clip `1` directory.
`permission_type`	Permission type associated with access. See "Permission Types" table for values.
`expires`	If `permission_type` is `1`, this is the expiration date/time, in format `MM/DD/YYYY:HH:MM:SS`. Otherwise blank.
`debitted_time`	If `permission_type` is `2`, this is time remaining (in seconds). If `permission_type` is `3`, this is the number of seconds of material the visitor has viewed. Otherwise blank.

where:

This example file, user1, has the following content, when player validation is in use:


*;00001d00-0901-11d1-8b06-00a024406d59;0
Secure/clip1.rm;0;0;*;*
Secure/directory;1;0;*;*
Secure/time.rm;0;2;*;300;*
Secure/time.rm;0;1;05/24/1970:06:12:32;300;*

Note
If you manually edit the files, be sure that any blank (or unused) fields use an asterisk (*) as a placeholder. Do not use a space for a placeholder.

	Note
If you manually edit the files, be sure that any blank (or unused) fields use an asterisk (`*`) as a placeholder. Do not use a space for a placeholder.

Guids Directory

The files in this directory are given the names of the unique client IDs from the registered clients, one per registered user. Each file contains only the name of the associated user name. For example, a file such as 00001d00-0901-11d1-8b06-00a024406d59 contains the name of the user, user1.

Logs Directory

This directory contains two files: reglog.txt and accesslog.txt.

Reglog.txt

Each line of reglog.txt represents the result of an attempt to register a visitor. This file has the following format:


status;userid;uuid;IP;register_time;url_redirect

where:


`status`	Result of user's attempt to connect: `0` Success`1` Failed (clientID not readable)`2` Failed (clientID already used)`3` Failed (RealAudio Player 3 or older)`4` No user (Must be entered previously in the database)`5` General failure
`userid`	Unique name of up to 50 characters.
`uuid`	Stores clientID.
`IP`	IP address from which user is attempting to connect.
`request_time`	Time of connection request.
`url_redirect`	If connection failed, URL to which user was redirected (see `redirect.txt`).

Accesslog.txt

Each line of accesslog.txt describes the result of an attempt to view a clip. This file is not created until authentication is enabled and the first user attempts to connect. Syntax of this file:


status;userid;uuid;ip;url;access_type;permission_on;start_time;end_time;total_time;
why_disconnect

where:


`status`	Result of user's attempt to connect: `0` access to clip granted `1` denied
`userid`	Unique name of up to 50 characters.
`uuid`	Stores playerID.
`ip`	IP address from which user is attempting to connect
`url`	Secured clip user is attempted to access.
`permission_type`	Permission type associated with access. See "Permissions Table" table for values.
`permission_on`	Permission type associated with url: `0` file (individual clip) `1` directory `2` none
`start_time`	Time/date clip started playing.
`end_time`	Time/date clip stopped playing.
`total_time`	Total time clip played.
`why_disconnect`	Reasons for disconnection: `0` client disconnected voluntarily `1` server access expired

Redirect Directory

Used only in player validation, the redirect directory contains files named after URLs that are restricted from unauthorized users. Within each file is the alternate URL to which RealServer sends the user if he or she tries to click the restricted URL. If no files are present in this directory, and the user attempts to click a URL to which he or she has not been given access, the user receives an error message.

Because certain characters that appear in URLs are illegal in file names, RealServer requires a substitution for these illegal symbols.

Substitutions
This character…	…is replaced with this sequence:
`/`	`+2f`
`\`	`+2b`
`+`	`+5c`

Thus, the URL "Secure/TopSecret.rm" would be converted to Secure+2fTopSecret.rm.

The URL within each file, however, is represented normally.

Using a Database for Authentication Data

This section describes the structure of the database templates included with RealServer.

To set up the database, see "Setting Up Other Types of Data Storage".

The database templates include five tables:

Users table-Together with the permissions table, contains the lists of who is registered and with what access.
Permissions table-Linked to the users table, lists specific clips and directories and the permissions associated.
Register_log table-Used if player validation is in use, it tracks the clientID.
Redirect table-Used in player validation only.
Access_log table-Used by the commerce feature.

Users Table

Gives the list of user names and passwords.

Users Table
Field	Description
`userid`	User name of up to 50 characters. Ties to permissions table.
`password`	In user authentication, this stores the password. Otherwise blank. Passwords are encrypted.
`uuid`	In player validation, stores clientID. In user authentication, an asterisk (*) appears in this field.
`uuid_writeable`	A flag set and used by RealServer: `0` clientID is in the database `1` the record has been created but the clientID is not yet registered with RealServer.

Permissions Table

Linked to the users table via the userid, this identifies the specific clips or directories and the type of access for each.

Permissions Table
Field	Description
`userid`	User name of up to 50 characters. Ties to Users table.
`url`	URL of secure directory or clip.
`url_type`	Whether URL is directory or clip: `0` clip `1` directory.
`permission_type`	Permission type associated with access. See "Permission Types" table for values.
`expires`	Permission expiration date and time, in format `MM/DD/YYYY:HH:MM:SS`. Used only if `permission_type` is `1` (dated). Otherwise blank.
`debitted_time`	If `permission_type` = 2 (countdown), this is the number of seconds remaining. If `permission_type`=3 (countup), this is the number of seconds of material the visitor has viewed. Otherwise blank.

Register_Log Table

The register_log table is only used if player validation is in use (indicated by UseGUIDValidation=True).

Register_log Table
Field	Description
`status`	Result of user's attempt to connect: `0` Success`1` Failed (clientID not readable)`2` Failed (clientID already used)`3` Failed (RealAudio Player 3 or older)`4` No user (Must be entered previously in the database)`5` General failure
`userid`	Unique name of up to 50 characters.
`uuid`	Stores clientID.
`ip`	IP address from which user is attempting to connect.
`request_time`	Time of connection request.
`url_redirect`	If connection failed, URL to which user was redirected (see Redirect Table, above).

Redirect Table

Redirect Table
Field	Description
`url`	URL of any secure clip or directory.
`url_redirect`	URL to which users could be redirected to if they are not allowed access to that clip. New URL must NOT be a secure URL.

The redirect table is only used in player validation.

Access_log Table

Used by the commerce feature to show which secure content has been accessed.

Access_log Table
Field	Description
`status`	Result of user's attempt to connect: `0` access to clip granted `1` denied
`userid`	Unique name of up to 50 characters.
`uuid`	Stores player ID.
`ip`	IP address from which user is attempting to connect.
`url`	Secured clip user is attempted to access.
`permission_type`	Permission type associated with access. See "Permission Types" table for values.
`permission_on`	Permission type associated with url: 0 file (individual clip) 1 directory 2 none
`start_time`	Time/date clip started playing.
`end_time`	Time/date clip stopped playing.
`total_time`	Total time clip played.
`why_disconnect`	Reason for disconnection: `0` client disconnected voluntarily `1` server access expired

Setting Up Other Types of Data Storage

Support for two types of databases is included.

To set up your Windows computer for ODBC compliance:

On the Start menu, point to Settings, and click Control Panel.
Double-click 32bit ODBC.
On the System DSN tab, click Add.
Select your ODBC driver from the list of drivers and click Finish.
In the ODBC SQL Server Setup dialog box, type the data source name. Click Select.
Type or browse for the path to your database file and click OK.
Click OK to exit the ODBC Data Source Administrator.

You must now tell RealServer where to find your database.

To set up the supplied database application on UNIX:

At a command line, start the database by typing the following:
```
./msql2d &
```
Create the database by typing the following:
```
./msqladmin create databasename
```
Note that whatever you type for databasename will need to match the database cited in the Databases list.
Create the tables using the database text file by typing the following:
```
.msql -h localhost databasename < ppvdemo.db
```
Be sure to include the less-than sign (<).