Worldgroup Script Keys Administrator's Guide
============================================

Introduction
------------

     The Worldgroup "locks & keys" security model has been a flexible
approach to the assigning of resources and access to both baseline and add-on
module features.  Typically, the administrator will assign a key to an
individual lock that protects access to resources from within a Worldgroup
application.  The lock is normally configurable by the system administrator
in the respective Worldgroup Level 3 CNF configuration option for that
particular application.  The only drawback to this approach is that it
becomes difficult to provide a highly customized key based on different
criteria without requiring the administrator to create and assign several
sets of keys.

     To show how this scenario works, let us consider the simple case where a
system administrator would like to create a special forum called  "Teenage
Girl Music Discussions".  As the name of the forum implies, we want this
forum to be accessible to only the patrons who are a) female; and b) are
teenagers.  We are going to be sure that our patron's user account
information is correct, since we will screen each new patron as their
signup-information is reviewed and confirmed.  At that point, we are ready to
switch them into a class that would allow them more access.  Because an
assistant administrator can be reasonably sure that an individuals account
information is valid, they can set about the task of assigning keys to
individuals either on a request basis or by adding the keys at the time the
account is verified.  In the case that our particular patron is a female user
that is between the ages of 13 and 19 inclusively (or whatever one would
consider a teenager) we will then assign that customer the key "GIRLTEEN".
The same holds true for users of other such classifications, such as
"BOYTEEN", "MANADULT", "WOMANADULT", etc.  Granted, classes can be made for
each of these classifications and the keys could become part of the
respective class key ring.  The overall result is that either more keys or
more classes are created.  Another observation, for this particular example,
is that an administrator may even be bothered with the necessity of updating
classes and/or keys in the event that the individual no longer fits within
the given constraints required to supply access.  For example, our 19 year
old patron could be turning 20 the next day -unless the administrator has a
utility to detect this and reassign keys, they may be sifting through reports
of users on a daily basis to adjust access accordingly.

     It should be said that the original designers of Worldgroup even saw
this limitation and provided a means to allow customizable keys.  This
approach worked well if you were a third-party developer or if you owned the
Worldgroup Developer's kit and necessary development tools.  The particular
approach that is referred to is the use of "pseudo-keys".  Pseudo-keys are
just as the name suggests -they are not quite keys in the sense to which the
typical administrator is accustomed.  An administrator was usually required
to purchase the source kit or seek the services of a third-party developer
when they wanted to create a customized set of keys that dynamically
determined at run-time whether or not the user was given the access to the
lock.  There are basically two drawbacks to this approach:  1) the expense in
time and money to outline the behaviors of the pseudo-keys and have them
developed; and 2) the fact that any change to the pseudo-key requires that
the new key (usually within an add-on) is re-compiled and the server shutdown
and restarted for the changes to take effect.

     Now enters the new approach to creating and assigning keys: the "script
key".  A script key is basically a key based on a pseudo-key.  One pseudo-key
is used to create many script keys, each of which can be highly customized
based on user, system and perhaps even exposed third-party module
information.  The only difference to this approach is that the key results
are interpreted by executing the script.  Scripts can be modified while the
server is running, without the need to shutdown and restart the server for
the changes to take effect.  The other benefit to the scripted keys is that
they use Microsoft's ActiveX scripting technologies.  If you have a Windows
9x or Windows NT 4.0/5.0 server with Windows Scripting Host installed, then
you have the capability of using Worldgroup ActiveX script keys.  By using
ActiveX scripting, administrators can use the various scripting languages
available:  VBScript, JavaScript, Perl and REXX.  If the administrator is
familiar with any of the scripting languages, they can leverage that
knowledge to create customizable access keys for Worldgroup 3.2.

The Script Pseudo-Key
---------------------

     Worldgroup Script Keys require the use of pseudo-keys to accomplish
their magic.  Since a pseudo-key consists of a prefix followed by extra
information to distinguish the key even further, this approach is used to
determine which script file will be executed.  Pseudo-key prefixes remain the
same as the server is running, however, the prefix for the pseudo-key used by
Worldgroup Script Keys is configurable as a CNF option.  If you change the
value of the script prefix, then any locks that use pseudo-keys with that
prefix must change as well.  Typically, the administrator will keep the
default prefix or change the prefix and leave it at that value indefinitely.
The default script prefix is "_SCP#".  Therefore, any key assigned to a lock
that uses a scripted key must begin with _SCP#.  The remaining portion of the
key name following the prefix specifies the filename portion of the prefix
file.  Worldgroup Script Keys allow you to customize both the resident
directory and a suffix for the script files.  The default values of
".\SCRIPTS" and ".WGS" are sufficient for most administrators.  These values
mean that all script files should reside in the 'SCRIPTS' subdirectory
beneath the Worldgroup Server and that all script files have a ".WGS"
extension.  Below is a list of the various CNF options that play a role in
the scripted key process:

SCPPFX	- Default value: _SCP#

     This Level 4 CNF option is used to determine the pseudo-key prefix that
will be used to tell the system that a scripted key is being used.  All keys
assigned to locks that begin with this prefix designate scripted keys, the
remainder of the pseudo-key name specifies a portion of the filename for the
script.

SCPPTH	- Default value: .\SCRIPTS

     This Level 4 CNF option is used to specify the path in which the script
files will reside.  The default specifies the directory named "SCRIPTS" which
is created directly beneath the Worldgroup Server directory.  All script
files referenced by the scripting pseudo-key must reside in this directory.

SCPEXT	- Default value: .WGS

     This Level 4 CNF option is used to specify the file extension that will
be added to fully qualify the script filename.  This option can be longer
than three characters, so that long filename support for the extension may be
used.

     Assuming that the default values are used for these CNF options, the
assignment of the pseudo-key: _SCP#USRCHK will cause the script with the full
path and filename ".\SCRIPTS\USRCHK.WGS" to be executed.  Below is an example
table that shows more examples of pseudo-key names, directories and
extensions along with their associate path\filenames.

Pseudo-Key    Path (SCPPTH)   Extension (SCPEXT)  Full File Specification
_SCP#SYSOP    C:\MYSCP        .Script             C:\MYSCP\SYSOP.Script
_SCP#MTEEN    .\KeyScripts    .SCP                .\KeyScripts\MTEEN.SCP
_SCP#CARUSER  F:\Scripts\Temp .WGS                F:\Scripts\Temp\CARUSER.WGS


Worldgroup Script Objects
-------------------------

     While a script is a useful in its own right, it does not do us any good
if there were not a way to use information pertinent to the task at hand.
With this in mind, Worldgroup Script Keys needed to make some (read-only)
information available to the script designer.  This is done by the use of
objects that expose the information of the user whose access is being
assessed to the script.  The name of the object that describes user account
information is "User".


The User Object
---------------

     The "User" object has the following properties, which can be read and
compared to determine the outcome of the access check:

UserID 		- the individual's user-id on the system
Channel        - the server channel on which the user is present
                 (-1 for ActiveH or some TCP/IP users)
Password       - The user's password
Name 		- The user's real name
Birthdate 	- The user's date of birth
Age            - The user's age
Sex            - The user's sex ("M" for male, "F" for female)
Address 		- used to access the various portions of a user's address
Phone 		- The user's phone number
System 		- The type of computer the user is using
Language       - The user's current language setting
ScreenWidth 	- The user's screen width
ScreenLength 	- The user's screen length for use with the Full Screen Editor
BreakLength 	- Number of lines to break text for the user
CreationDate 	- The date the user's account was created
LastUsedDate 	- The date that the account was last used
AccessFlag     - Used to determine what type of remote administration the
                 user possesses
EmailLimit 	- The e-mail limit reached so far
PermanentClass - The user's permanent class
CurrentClass 	- The class in which the user currently resides
SecondsOnToday	- The number of second the user has been online today
DaysLeftInClass 	- The number of days left the user has in his class
DebtForgiveDays     - The number of days since the user's debt was last
                      forgiven
CreditsAvailable    - The number of credits a user has available (negative
                      if they are in debt)
TotalFreeCredits    - The total number of free credits given to this user
TotalPaidCredits    - The total number of paid credits given to this user

     In addition to the various properties of the user object, there is also
one method, 'HasKey()' This method works very similar to the Worldgroup API
function of the same name, only that instead it works from the script and
uses static keys.  Other scripted keys cannot be used from within scripted
keys themselves.  All operations done within a script key are performed in
the context of the user whose access is being checked.

The Result Object
-----------------

     The result object is what is used to set the result of the key check. If
you wish the script to grant access to the resource before exiting, set the
value of result object to true.  If you wish to deny access, set the value of
the result object to false.

Worldgroup Script Key Examples
------------------------------

     It is beyond the scope of this paper to describe the use of VBScript or
the other scripting languages available for ActiveX scripting. Documentation
for VBScript and JavaScript can be found on Microsoft's web site at:

     http://msdn.microsoft.com/scripting.

     For the sake of our examples, we will stick to the use of VBScript, a
scripting language that is similar in fashion to Visual Basic.  If you have
worked with any .ASP pages for Microsoft's Internet Information Server or
have used VBScript for client scripting or the Windows Scripting Host, then
you already know how to create Worldgroup Script Keys.  We will also stick to
using the default values for the CNF configuration options, however, the
administrator may feel free to modify these as desired when they are
comfortable with how the keys work.

Grouping Users Without Classes
------------------------------

     Let us create a useful script by revisiting the "Teenage Girl Music
Discussions" example.  In this example, we want to use a discussion forum to
narrow down a target market and attempt to reduce the amount of 'noise'
introduced into a publicly accessible forum.  So with that in mind, we wanted
to create a key to limit access to one of our forums.  This key had the
properties that only our female patrons could be allowed access --and even
then if they were between the ages of 12 and 19 inclusive.  Naturally, the
topic will imply that the forum pertains to music discussion.  An
administrator could possibly use information shared in this forum to
influence marketing decisions among this particular group of individuals. We
will start by creating the script file that will check the sex and age
properties of the user.  The first step is to come up with the name of our
script file.  FTEEN.WGS is a good start.  Create this new file in the SCRIPTS
subdirectory under the Worldgroup Server directory.  We have made the
extension ".WGS" because that is what the Level 4 CNF option SCPEXT is set to
and we will reference the script itself as a key by the name "_SCP#FTEEN".
Below is the Visual Basic script text that we will place in FTEEN.WGS.

------------------------------ cut here -------------------------------

Result=((User.Sex="F") And ((User.Age > 11) And (User.Age < 20)))

------------------------------ cut here -------------------------------

     Next, we are going to create our new "Teenage Girl Music Discussions"
forum.  When we create our forum, we will specify "Zero" for our forum's
non-privileged access, and specify the access level we want for privileged
users, which may be then be set to "Upload".  Next, when specifying the
"Privileged Key", use the value of our script key, which is "_SCP#FTEEN".

     When the users on the system get forum listings or for that matter, read
and write in the forums, their access will be checked using this script key.
If the check fails, then the user will not have access to that forum.  Notice
that a key did not have to be added neither to the user's key ring nor to
their class key ring for this security to take effect.  All security checking
is done from within the script itself.  Also, if the user were to grow a year
older the following day, the dynamic quality of the script itself will ensure
that the person no longer had access to the forum.

Limiting Resource Usage
-----------------------

     Another example of restricting usage to resources may not necessarily be
due to the fact that the user does not normally have access to the resource,
but perhaps is restricted to its use at certain times.  For example, an
administrator notices that during the day, his multi-user dungeon module gets
the most traffic from the hours of 3:00pm to 10:00pm (after school and before
bedtime, although it's probably more like 3:00pm and 3:00am).  During this
time, he wants to keep as many channels open on his modems to allow local
callers into the system.  In order to make sure that a busy beaver sending
out faxes cannot take up his modems during this time, he uses a script key to
deny access to the fax application.  By checking the time of day (a feature
offered by the VBScript language), he can deny access to Fax/Online users
during these peak gaming periods.

     We will call the script "FAXTIME.WGS".  In keeping with our script key
naming scheme, the pseudo-key we need to use is "_SCP#FAXTIME".  Now, we will
modify the Level 3 CNF options FAXAGKY and FAXAHKY to use this pseudo-key.
Now our script can govern any access to the fax application.  If we decide
later that the hours need to change, all we need to do is edit the script,
even if the server is still running.  The next page shows the VBScript code
that we would use in order to provide access based on the time of day.

------------------------------ cut here -------------------------------

Result=((Hour(Time) < 3) And (Hour(Time) > 8))

------------------------------ cut here -------------------------------


Granting Access for Specific Time Periods
-----------------------------------------

     In our last example, we saw how the administrator could modify access to
their resources based on peak usage.  In this example, the same administrator
is now becoming overwhelm by the number of users playing his online
multi-user dungeon module and has been receiving complaints from users that
cannot play the game because other serious gamers are monopolizing its time.
In order to alleviate the traffic and make the game more fair, the
administrator decides to allow users to choose the days they wish to play.
Using a simple case, he decides to create a key to allow some users to play
only on Monday, Wednesday and Friday and another key to allow others to play
only on Tuesday, Thursday and Saturday.  The administrator decides to allow
Sunday a "first-come, first serve" day so that anyone can have access.  Next,
the administrator sends around e-mail to all individuals, allowing them to
choose the slot of days on which they can access the game.  The user is then
given a key to correspond to their choice.  (For the sake of keeping this
example simple, we will assume that there are two groups roughly equal in
number for each slot of days.)  So, we create two keys, DAYSMWF and DAYSTWTH
(the key suffixes correspond to the days they have access to make them easier
to remember.)  Now, we will create a script key which will do the checking
for various days, we will call the script file MUDDAYS.WGS.  Naturally, the
name of the script key that we would use to control access to our multi-user
dungeon module would be _SCP#MUDDAYS.  To perform the necessary checking for
the appropriate key and day set, we will use the following script:

------------------------------ cut here -------------------------------

Select Case Day(Date)
	Case vbMonday,vbWednesday,vbFriday
		Result=User.HasKey("DAYSMWF")
	Case vbTuesday,vbThursday,vbSaturday
		Result=User.HasKey("DAYSTWTH")
	Case Else
		Result=True
End Select

------------------------------ cut here -------------------------------


Free Preview Periods
--------------------

     A system administrator decides to whet the appetites of potential
customers by granting access to a popular application for a limited period of
time.  Since the scrabble-type game is one of the more popular haunts, the
administrator decides to give access to the game to all users for the week of
March 28, 1999 to April 4, 1999, inclusive.  Typically, a user with
"SCRABKEY" is always granted access to the module, so we want our script to
not only allow access to these individuals, but to also allow anyone else
through during the trial period.  To add an extra twist to the problem, we
also want to be able to deny access to users that present a problem by
harassing other users.  We well create a generic "NOACCESS" key that we will
use within this (and perhaps other) scripts.  We will call the script file
SCRBPRVW.WGS, which will represent the scripted key for those who are going
to be allowed to preview the scrabble application.  Like before, we will use
the typical pseudo-key name for our key:  _SCP#SCRBPRVW.  The script that
will solve our particular access problem will look like the following:
(Note: date comparisons will be done according to how you have your localized
settings configured under Windows)

------------------------------ cut here -------------------------------

If User.HasKey("NOACCESS") Then
	Result=False
Else
	Result=(User.HasKey("SCRABKEY") Or ((Date > "3/27/1999") And (Date < "4/5/1999")))
End If

------------------------------ cut here -------------------------------


     Because the key will properly approve access to the module based on the
date, the administrator can remove the necessary code that does extra
checking at their leisure (even after the free period date) without
compromising security.

Providing Rewards Easily with Elaborate Requirements
----------------------------------------------------

     A system administrator wants to collect valuable marketing research from
his customers.  As an incentive, the administrator wants to allow access to
an application as a reward for participating in this market research.
Normally, the administrator would create a poll and choose to have the poll
grant the user a key for taking the poll.  In our case however, it is a
little more complicated.  Instead, we have a series of five polls, each poll
is unrelated to one another in terms of content.  Our administrator wants to
grant access to an application to each user that has taken at least three out
of the five polls, no less.

     The first step would be for our administrator to create the five polls,
then assign the granted keys as such: POLL1, POLL2, POLL3, POLL4 and POLL5.
Now, when the user takes one of they five polls, they are granted the
appropriate key.  The next step is to devise a script key that will be used
to determine whether or not the user has taken at least three of the polls.
We will call our script file POLLAXS.WGS, our associated pseudo-key that we
would use to allow access to our application would be called _SCP#POLLAXS.

     The script that will determine that the user has taken the polls will
look like the following:

------------------------------ cut here -------------------------------

Dim PollCount

PollCount=0
If User.HasKey("POLL1") Then
	PollCount=PollCount+1
End If
If User.HasKey("POLL2") Then
	PollCount=PollCount+1
End If
If User.HasKey("POLL3") Then
	PollCount=PollCount+1
End If
If User.HasKey("POLL4") Then
	PollCount=PollCount+1
End If
If User.HasKey("POLL5") Then
	PollCount=PollCount+1
End If
Result=(PollCount > 2)

------------------------------ cut here -------------------------------


     The example above will make sure that as long as three of the polls have
been taken (regardless of which three) then the user will have access to the
application.  The script could be modified slightly if the administrator
wanted to introduce other constraints, for example, if they required one
mandatory and two optional polls to be taken.

Boolean Key Operations
----------------------

     Quite often an administrator may find it useful to grant access to an
application based upon a logical expression used to determine whether or not
a user does or does not hold a specific set of keys.  To elaborate further,
the administrator would want to perform a series of checks to make sure the
user holds certain keys and will revoke access if they hold others.  For
example, a system administrator has the following paid-monthly classes, each
with a given set of keys for the respective class:

Class               Keys
BronzeUser          COMMERCE, MONTH, BRONZE
SilverUser          COMMERCE, MONTH, SILVER
GoldUser            COMMERCE, MONTH, GOLD

     The administrator wants to set up access to certain commerce-based
applications, but they have one particular application to which they want to
grant access to only 'SILVER' and 'GOLD' users.  In this case, they wish to
grant access if the user has both the COMMERCE key and the MONTH key, but not
the BRONZE key.  Below is the script that would accomplish just that:

------------------------------ cut here -------------------------------

Result=(User.HasKey("COMMERCE") And User.HasKey("MONTH")
       And (Not User.HasKey("BRONZE")))

------------------------------ cut here -------------------------------

     As you can see, the ability to have "anti-keys" by use of the 'Not'
operator makes scripted keys powerful just for simple tasks.

Conclusion
----------

     Each of the scenarios in this document present real examples of
situations that require the need for dynamic security.  It is quite probable
there are several more scenarios that can be presented, which address other
needs for the ability to dynamically grant or revoke access to resources.
While all of the examples above can be done using pseudo-keys, there are
still many advantages to using scripted keys:

* A Worldgroup Developer's kit and required development tools are necessary
  to create pseudo-keys which mean the following:
     * The administrator must commit to the extra expense to develop his or
       her own pseudo-keys; or
     * An administrator must commit to the extra expense to have a
       third-party developer create the pseudo-key.

* Adding pseudo-keys (from multiple developers) requires that a new module is
  created for the Worldgroup server, whereas the Worldgroup Script Keys only
  require one add-on to run many scripts.

* The actual logic governing the pseudo-key needs to be planned in advance
  before the key is compiled.  With a Worldgroup Script Key, the script file
  can be created 'on-the-fly' and simply do nothing more than deny access
  until the administrator is ready to add the logic.

* If changes need to be made to a pseudo-key, the key must be recompiled and
  the server needs to be shut down and restarted.  With Worldgroup Script
  Keys, however, the administrator can implement the logic for the key at
  their leisure, even while the server is running.  When the script file is
  edited and saved, changes take effect immediately.

* Pseudo-keys require that they be developed in C or C++ while Worldgroup
  Script Keys can be developed in any scripting language available to
  Microsoft's ActiveX Scripting Engine.  Administrators who already know
  VBScript or JavaScript to develop .ASP pages or client side script using
  those languages can leverage their existing knowledge to create Worldgroup
  Script Keys.

* Because pseudo-keys require modules and .MDF files, they are less
  convenient to share with other administrators.  Since Worldgroup Script
  Keys are nothing more than text, scripts can be shared with Worldgroup
  administrators via e-mail, forums or even collections of script files
  conveniently compressed.

* Because the price is significantly lower than that of a Worldgroup
  Developer's kit, the module pays for itself after only one use, providing a
  quick return on investment.  It is probably more correct to expect that the
  typical administrator will find ways to use this product that have not yet
  been discovered.
