Customizing an Authentication Registration Database

RealServer 5.0 stores user name and password information in either a text file/directory structure or a database, for which several templates are included with RealServer.

This document describes the database query structure in generic language for those who want to use their own database. If you are going to be using a programming language other than C or C++, you will need to write your own library functions for registering users with RealServer and giving them permissions to specific media. The discussion of the flat-text databases and non-SQL database structure used by the Authentication portion of RealServer can be found in Appendix B of the RealServer 5.0 Administration Guide. This document is meant to be a general guide for SQL database users, and instructions on actual implementation are not given here. Sample Perl code is provided.

This section assumes that you have kept the database specifications as presented in Appendix B of the RealServer 5.0 Administration Guide.

Warning: this information is intended as a guideline only. It does not perform any error checking.

There are three steps involved:

  1. Register the user.
  2. Add the user to the register_log table.
  3. Give the user access to directories or clips.


Registering the User

First you must register the user with the pnserver. If you are using a SQL-compliant database, use a query such as the following:

INSERT INTO users (userid, password, uuid, uuid_writeable) VALUES (
        'user id here',
        'md5 encrypted password',
        'uuid here',
        1
)

The SQL query above will add the to the "users" table of the Authentication database. Note: The uuid field is not required for User-based authentication. For User-based authentication, use a blank string ('') for the value of the uuid.

Please note that the password is MD5 encrypted! See the Using the Password Tool section in Chapter 5 of the RealServer 5.0 Administration Guide for more details on how to form the correct password string.


Adding the User to the Register_Log Table

Next you must add this user to the "register_log" table. Use something like the following:

INSERT INTO register_log (status, userid, uuid, ip, request_time, url_redirect) VALUES (
        0,
        'user id here',
        'uuid here',
        'ip address',
        'current date/time (MM/DD/YYYY:HH:MM:SS)',
        'url you will send them to after finishing up here'
)

Note: For User-based Authentication, you can simply employ a space (" ") for the values of the uuid, ip, and url_redirect fields. In Player-based Authentication these are mandatory fields.


Giving Users Access to Directories or Clips

Now that the user is registered with RealServer, you must give him or her permissions to the specified media. This step varies depends on what type of event you are running. (For more details on each of these access types, see the Access Control section in Chapter 5 of the RealServer 5.0 Administration Guide.)

Event-based Access

To give a user event-based access to an entire directory of content, use a SQL query similar to the following:

INSERT INTO permissions (userid, url, url_type, permission_type, expires, debitted_time) VALUES (
        'user id here',
        'relative url of directory',
        1,
        0,
        ' ',
        0
)

To give a user access to specific clips, see the Event-based Access section in Chapter 5 of the RealServer 5.0 Administration Guide, as well as the database specification in Appendix B for more details.

Calendar-based Access

To give a user calendar-based access to an entire directory of content, use a SQL query similar to the following:

INSERT INTO permissions (userid, url, url_type, permission_type, expires, debitted_time) VALUES (
        'user id here',
        'relative url of directory',
        1,
        1,
        'date this event expires (MM/DD/YYYY:HH:MM:SS)',
        0
)

To give a user access to specific clips, see the Calendar-based Access section in Chapter 5 of the RealServer 5.0 Administration Guide, as well as the database specification in Appendix B of the same book for more details.

Duration-based Access:

To give a user duration-based access to a specific clip, use a SQL query similar to the following:

INSERT INTO permissions (userid, url, url_type, permission_type, expires, debitted_time) VALUES (
        'user id here',
        'relative url of clip',
        0,
        2,
        ' ',
        time
)

The "time" variable above should be the number of seconds of total viewing time that you wish to give the user. The pnserver will automatically adjust this value as the user views your content.

To give access to entire directories, see the Duration-based Access section in Chapter 5 of the RealServer 5.0 Administration Guide, as well as the database specification in Appendix B for more details.


That's it! After you successfully complete the three steps above, your user will be registered, and can begin to download your media. If, after taking these steps, the user still does not have access to the content, make sure that you are inserting appropriate values into each field, and double-check your procedure against this document.


Example code in Perl 5.x

The following example shows how to give a user access to an mSQL authentication database using Perl 5.x with the MD5 and Msql P5 modules installed. Note that this code is an example only--it does not do any necessary error checking, and should not be used as-is! It is meant to be a guideline by which you can create your own Perl programs to correctly interface with the RealServer.

#!/usr/local/bin/perl
#
# sample-rs-auth.pl
#
# This is meant simply as a basic guideline for using Perl to 
# interface with the RealServer Authentication feature. This example 
# assumes that you have the MD5 and Msql P5 modules installed on your 
# system. To install those Perl modules, visit
# http://www.perl.com/CPAN/
#
# This program assumes that you will be using User-based  Authentication,
# so it utilizes some shortcuts while inserting into the database; you
# can use them if you want.
use MD5;
use Msql;
## set some preliminary vars ##
$user_id = 'foo';
$password = 'bar';
$realm = 'Same String as in your server.cfg file!';
$db_host = 'my.db.host';
$auth_db_name = 'auth';
## determine our password string ##
$md5 = new MD5;
$md5->add(join(":",$user_id,$realm,$password));
$md5_passwd = $md5->digest();
$md5_passwd = unpack("H*",$md5_passwd);
## find out the current date and time (MM/DD/YYYY:HH:MM:SS format) ##
@tnow = localtime;
$current_date = join("/",$tnow[4]+1,$tnow[3],$tnow[5]+1900);
$current_date .= ":" . join(":",$tnow[2],$tnow[1],$tnow[0]);
## connect to the database ##
$dbh = Msql->connect($db_host,$auth_db_name);
## insert the user into the "users" table (step 1 from above) ##
$sql = "INSERT INTO users (userid, password, uuid, uuid_writeable) VALUES (" .
	"'$user_id', '$md5_passwd', ' ', 1 )";
$dbh->query($sql);
## insert the user into the "register_log" table (step 2 from above) ##
$sql = "INSERT INTO register_log (status, userid, uuid, ip, request_time, " .
	"url_redirect) VALUES (" .
	"0, '$user_id', ' ', ' ', '$current_date', ' ' )";
$dbh->query($sql);
## give the user access to the "pnm://server/secure" directory ##
## note: this is event-based access (see step 3 above) ##
$sql = "INSERT INTO permissions (userid, url, url_type, permission_type, " .
	"expires, debitted_time) VALUES (" .
	"'$user_id', 'secure', 1, 0, ' ', 0 )";
$dbh->query($sql);
## that's it. Print success ##
print "Success! $user_id has been added to the database!\n";

Again, we can not emphasize enough that you should not use the above code! See the md5(1) man page for more details using MD5, and the Msql-P5 specification for appropriate error-handling procedures that should have been implemented above.