Procedure Model

The following pages describe the modules, functions, and pages to be developed as part of the new system. Each of the following modules can be assigned to different developers as a self-contained system component.

Web Pages

user/index.html

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: user/index.html Assigned to: Reference:
Description	This pure HTML page contains the descriptions and navigation for users, prospective users and members to interact with the UMS.
Implementation Skills	HTML
Parameter List	None
Called By:	GPFN Main page, other pages on the GPFN web site
Can Call:	user/join.html user/upgrade.html user/myacct.html (Phase 2)
Function Description	Page invites viewer to join the GPFN listing the benefits of membership and other service upgrade options. (Phase 2)A link to the myacct.html page so users can view their account information is also present.
Possible Exit Conditions and Return Values	None required
Sign Off by:	Membership Committee or GPFN Board Designate

user/join.html

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: user/join.html Assigned to: Reference:
Description	This HTML page contains the descriptions of the membership and user classes of the Great Plains Free-Net for which they wish to apply.
Implementation Skills	HTML
Parameter List	None
Called By:	user/index.html
Can Call:	user/agree.html user/index.html /index.html
Function Description	The page describes the three classes of user: Registered User, Individual Member and Institutional Member and the benefits and features of each class. A Cancel link redirects users to the user/index.html page and a GPFN button takes the viewer back to the main GPFN page.
Possible Exit Conditions and Return Values	None
Sign Off by:	Membership Committee or GPFN Board Designate

user/agree.html

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: user/agree.html Assigned to: Reference:
Description	This page contains the user agreement, acceptable use policy and other requirements the viewer must agree to before obtaining a GPFN account.
Implementation Skills	HTML, HTML forms, Javascript
Parameter List	None
Called By:	user/join.html
Can Call:	user/apply.html user/index.html /index.html
Function Description	The page contains the text to which a prospective user must agree before an account application is received and processed. The viewer notes acceptance of this agreement by clicking an “Accept” button at the bottom of the page. The Accept button directs them to the apply.html page with the value “UA_accept” appended to the URL as a Query String parameter. A “Decline” button returns them to the user/join.html page. A “GPFN Home” button returns them to the GPFN main page.
Possible Exit Conditions and Return Values	If the viewer clicks the “Accept” button, they are sent to user/apply.html?UA_accept. If the viewer clicks the “Decline” button, they are sent to user/join.html If the viewer clicks the “GPFN Home” button, they are sent to /index.html
Sign Off by:	Membership Committee or GPFN Board Designate

user/apply.html

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: user/apply.html Assigned to: Reference:
Description	This HTML page contains a form to gather the information required to process an application to the GPFN
Implementation Skills	HTML, HTML Forms, Javascript
Parameter List	Query String must contain value “UA_accept”
Called By:	user/agree.html
Can Call:	user/validate.cgi user/index.html user/join.html /index.html
Function Description	The URL to which the user arrives must be “user/apply.html?UA_accept”. If the “?UA_accept” portion of the URL is missing, they should be redirected to the user/join.html page. If the UA_accept parameter is received the page displays an HTML form. This form must first query the viewer for the type of account they want. A pop-up menu named “Membership_Class” should list “Registered User”, “Individual Member” and “Institutional Member and send values “Registered”, “Individual”, and “Institution” respectively. The form must also obtain the following data from the user. Items marked with a () are required and must be present before the form is processed: User_FirstName User_LastName User_Initial User_Salutation (popup one of Mr., Mrs., Ms., Dr., Rev.,) User_Organization (only required for an Institutional Membership) User_Title (only required for an Institutional Membership) User_StreetAddress1 User_StreetAddress2 User_City User_Province User_Country User_PostalCode User_HomePhone User_WorkPhone User_Age (If under 18 and needing a parent’s approval for an account) *User_InitialPassword (entered as a password field of 6-8 characters. Users should be told to only use letters, numbers, and underscores and to NOT use any real word variation of a real word, any variation of their name or username) If the application is for an individual or institutional membership the following fields must also be gathered Upgrade_UserName (the requested username by the prospective member) Upgrade_toPPP (check box: True=”1” default: False=’0’) Upgrade_toDB (check box: True=”1” default: False=’0’) Upgrade_DBName (textfield—only meaningful if Upgrade_toDB is checked) Upgrade_toVirtualDomain (check box: True=”1” default: False=’0’) Upgrade_VirtualDomainName (textfield—only meaningful if Upgrade_ toVirtualDomain is checked) Upgrade_toSSL (check box: True=”1” default: False=’0’) Upgrade_toListserver (check box: True=”1” default: False=’0’) Upgrade_ListserverName (textfield—only meaningful if Upgrade_toListserver is checked) Upgrade_toAliases (user enters a number default: False=’0’) Upgrade_AliasExtAddress (textfield—only meaningful if Upgrade_toAlias is checked) Upgrade_AliasGPFNAddress (textfield—only meaningful if Upgrade_toAlias is checked Upgrade_Quota1 (check box: True=”5” default: False=’0’) Upgrade_Quota2 (check box: True=”5” default: False=’0’) Upgrade_Quota3 (check box: True=”5” default: False=’0’) All requests for upgrades should list the annual (and possibly with Javascript the pro-rated) amounts of the upgrade.
Possible Exit Conditions and Return Values	If UA_accept parameter is missing, user is redirected back to user/join.html If any of the required fields listed above are left blank, the submit button should be disabled or the user should be directed to fill in these fields before proceeding.
Sign Off by:	Membership Committee or GPFN Board Designate

user/upgrade.html

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: user/upgrade.html Assigned to: Reference:
Description	This HTML page contains the terms and conditions related to any upgrade option including prices.
Implementation Skills	HTML
Parameter List	None
Called By:	user/index.html
Can Call:	user/login.cgi?upgrade.cgi user/index.html /index.html
Function Description	The page lists all relevant details for users to be able to decide what options to select in upgrading their account. Users can click to move forward to the login.cgi page before formally request an upgrade, or click a cancel button to go back the user/index.html page or a GPFN home button.
Possible Exit Conditions and Return Values	If the user clicks to apply for an upgrade, control passes to URL: login.cgi?upgrade.cgi. The “upgrade.cgi” string allows the login.cgi script to redirect the user to the correct option page if the login is successful.
Sign Off by:	Membership Committee or GPFN Board Designate

user/myacct.html

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: user/myacct.html (Phase 2) Assigned to: Phase 2 Reference:
Description	This HTML page contains a description of the options available to the account holder in viewing or managing his or her account history and configuration
Implementation Skills	HTML
Parameter List	None
Called By:	user/index.html
Can Call:	user/login.cgi?myacct.cgi user/index.html /index.html
Function Description	Users can click to move forward to the login.cgi page before formally viewing their account history or settings or altering their account configuration, or click a cancel button to go back the user/index.html page or a GPFN home button.
Possible Exit Conditions and Return Values	If the user clicks to view their account, control passes to the login.cgi?myacct.cgi. The “myacct.cgi” string is used to allow the login.cgi script to redirect the user to the correct option page if the login is successful.
Sign Off by:	Membership Committee or GPFN Board Designate

vol/index.html

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: vol/index.html Assigned to: Reference:
Description	This pure HTML page allows the volunteer to choose between processing applications for accounts and upgrades and processing financial transactions.
Implementation Skills	HTML
Parameter List	None
Called By:	Directly by the user. Page is behind htaccess controls.
Can Call:	vol/listapps.cgi vol/upgrades.cgi vol/receipts.cgi vol/invoices.html vol/acct.html (Phase 3)
Function Description	The volunteer can choose: a link to listapps.cgi to get a list of all new account applications for processing; a link to upgrades.cgi to get a list of all upgrade requests to existing accounts; a link to receipts.cgi to process a receipt to a renewal invoice; a link to invoices.html to select the options before creating a new invoice cycle or sending statements to accounts; a link to acct.html to get a list of available account management options so the volunteer can view or alter the user’s account history or settings (Phase 3)
Possible Exit Conditions and Return Values	None
Sign Off by:	Membership Committee or GPFN Board Designate

vol/invoices.html

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: vol/invoices.html Assigned to: Reference:
Description	This HTML/Javascript page allows the volunteer to choose the options before generating new invoices or reminder notices. The volunteer can choose to generate an annual invoice cycle for all members, display an invoice for a particular user, generate an annual invoice for a particular user, display statements for all members, or display a statement for a particular user. As well, the form allows the volunteer to choose to e-mail the statements or invoices to the user, or to print them to the screen, or to print them to a tab delimited file which can be downloaded. The number and identity of the invoices or statements e-mailed or displayed in this way corresponds to the choices made in the preceding paragraph.
Implementation Skills	HTML, Javascript, HTML forms
Parameter List	None
Called By:	vol/index.html
Can Call:	vol/geninvoice.cgi vol/index.html
Function Description	The HTML form gathers the following information before passing the data to the geninvoice.cgi script: Invoice_Count (Radio Button set to “1” or “all”) User_UserName (Textfield matching the data definition entry and must be filled in with the UserName of the User for whom the invoice/statement is to be created only if the Invoice_Count is set to “1”) Type_Switch (Radio Button set to “NewInvoice”, “ExistingInvoice” or “Statement”. These values will have English equivalences such as “Generate New User Invoices”, “View an Existing User Invoice”, or “Print User Statements”. Javascript should implement the rule that if Invoice_Count is set to 1, then the NewInvoice option is NOT available. *Medium_Switch (Radio Button set to “E-Mail” or “Screen” A Submit button forwards the form data to the geninvoice.cgi. A Cancel button returns the volunteer to the vol/index.cgi page.
Possible Exit Conditions and Return Values	The form and Javascript should correctly handle all data exceptions. Data should be passed to the geninvoice.cgi script. Cancels should return control to index.html
Sign Off by:	Membership Committee or GPFN Board Designate

vol/invoice.tmpl

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: vol/invoice.tmpl Assigned to: Reference:
Description	This HTML page forms a dynamically generated invoice. The template file is used by the geninvoice.cgi developer to present an attractive and visually consistent invoice to the user.
Implementation Skills	HTML
Parameter List	None
Called By:	vol/geninvoice.cgi
Can Call:
Function Description	The template file includes all HTML and graphics to display an invoice on a web browser window. It must be visually equivalent whether displayed in Internet Explorer, Netscape Navigator or Opera. Spaces should be left for user identification, date of invoice, invoice charges and item descriptions, payment terms and options, instructions to print this page, and GPFN identification and remittance information
Possible Exit Conditions and Return Values	The page is not called directly but will be cut and pasted into cgi scripts.
Sign Off by:	Membership Committee or GPFN Board Designate

vol/stmt.tmpl

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: vol/stmt.tmpl Assigned to: Reference:
Description	This HTML page forms a dynamically generated statement. The template file is used by the geninvoice.cgi developer to present an attractive and visually consistent statement to the user.
Implementation Skills	HTML
Parameter List	None
Called By:	vol/geninvoice.cgi
Can Call:
Function Description	The template file includes all HTML and graphics to display a statement on a web browser window. It must be visually equivalent whether displayed in Internet Explorer, Netscape Navigator or Opera. Spaces should be left for user identification, dates and amounts of invoices and receipts, payment terms and options, outstanding balance and the aging of the balance and GPFN identification, instructions to print this page, and remittance information
Possible Exit Conditions and Return Values	The page is not called directly but will be cut and pasted into cgi scripts.
Sign Off by:	Membership Committee or GPFN Board Designate

vol/rcpt.tmpl

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: vol/rcpt.tmpl Assigned to: Reference:
Description	This HTML page forms a dynamically generated receipt. The template file is used by the receipts.cgi developer to present an attractive and visually consistent statement to the user.
Implementation Skills	HTML
Parameter List	None
Called By:	vol/receipts.cgi
Can Call:
Function Description	The template file includes all HTML and graphics to display a receipt on a web browser window. It must be visually equivalent whether displayed in Internet Explorer, Netscape Navigator or Opera. Spaces should be left for user identification, date, instructions to print this page, amount and payment method as well as GPFN identification and a thank-you message.
Possible Exit Conditions and Return Values	The page is not called directly but will be cut and pasted into cgi scripts.
Sign Off by:	Membership Committee or GPFN Board Designate

vol/accept.tmpl

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: vol/accept.tmpl Assigned to: Reference:
Description	This HTML page forms a dynamically generated statement. The template file is used by the validate.cgi developer to present a user acceptance agreement for signature and mail-in by the new account applicant.
Implementation Skills	HTML
Parameter List	None
Called By:	user/validate.cgi
Can Call:
Function Description	The template file includes all HTML and graphics to display a user acceptance agreement on a web browser window. It must be visually equivalent whether displayed in Internet Explorer, Netscape Navigator or Opera. Spaces should be left for user identification, legal terms and obligations, provisions for under-age applicants, payment terms and options, and GPFN identification, instructions to print this page, and remittance information
Possible Exit Conditions and Return Values	The page is not called directly but will be cut and pasted into cgi scripts.
Sign Off by:	Membership Committee or GPFN Board Designate

vol/acct.html

Procedure Model Type: (X)Web Page ( )CGI Script ( )Shared Library ( )System API Name: vol/acct.html (Phase 3) Assigned to: Phase 3) Reference:
Description	This HTML page lists the account management options available to the volunteer and collects the information on which user account to display.
Implementation Skills	HTML, HTML Forms
Parameter List	None
Called By:	vol/index.html
Can Call:	vol/history.cgi vol/quota.cgi vol/passwd.cgi vol/forward.cgi vol/filter.cgi vol/expire.cgi vol/purge.cgi
Function Description	Not yet fully defined
Possible Exit Conditions and Return Values	Not yet fully defined
Sign Off by:	Membership Committee or GPFN Board Designate

CGI Procedures

user/validate.cgi

Procedure Model Type: ( )Web Page ( X )CGI Script ( )Shared Library ( )System API Name: user/validate.cgi Assigned to: Reference:
Description	This script takes the information from the user/apply.html form, verifies that all required data is present before attempting to create a new user request.
Implementation Skills	PERL, CGI, SQL
Parameter List	Membership_Class User_FirstName User_LastName User_Initial User_Salutation User_Organization User_Title User_StreetAddress1 User_StreetAddress2 User_City User_Province User_Country User_PostalCode User_HomePhone User_WorkPhone User_Age User_InitialPassword Member_UserName (the requested username by the prospective member) Upgrade_toPPP (check box: True=”1”) Upgrade_toDB (check box: True=”1”) Upgrade_toVirtualDomain (check box: True=”1”) Upgrade_toSSL (check box: True=”1”) Upgrade_toListserver (check box: True=”1”) Upgrade_toAliases (user enters a number) Upgrade_Quota1 (check box: True=”5”) Upgrade_Quota2 (check box: True=”5”) Upgrade_Quota3 (check box: True=”5”)
Called By:	user/apply.html
Can Call:	lib/uname_generate.pl lib/uname_test.pl lib/pw_check.pl
Function Description	The script verifies that the user has supplied all required values. The procedure model for the user/apply.html page lists these requirements. They include: Membership_Class, User_FirstName, User_LastName, User_Salutation , User_StreetAddress1, User_City, User_Province, User_Country, User_PostalCode, User_Age, User_InitialPassword. If Membership_Class is “Institution” or “Individual”, the following additional fields must also be gathered: Member_UserName, Upgrade_toPPP, Upgrade_toDB, Upgrade_toVirtualDomain, Upgrade_toSSL, Upgrade_toListserver, Upgrade_toAliases, Upgrade_Quota1, Upgrade_Quota2, Upgrade_Quota3. If Membership_Class is “Institution” User_Organization, and User_Title are also required fields. If Membership_Class is “Registered”, then the library function “uname_generate.pl” is called to return the next sequential userid. Otherwise, the “uname_test.pl” is called to verify that the value supplied in the Member_UserName field is unique and valid. If uname_generate.pl or uname_test.pl returns an error, the script returns with error condition 1 below. The value of User_InitialPassword is tested with a call to “pwcheck.pl”. If the test fails, the script returns with error condition 1 below. The values from the form are inserted as a new record in the Database User table. In addition, the following additional fields are populated as follows: User_IsActive = “Pending” User_Since = current timestamp User_IsMember = “Y” if Membership_Class is “Individual” or “Institution”, otherwise User_Is_Member = “N” User_EnteredBy = Web Server’s ‘REMOTE_USER’ value Retrieve the value of User_Number from the new record If Membership_Class is ‘Registered’, proceed to step 14 below. If Membership_Class is not “Registered”, insert a new record in the Member table with the following values: User_Number = the User_Number of the just created User record in the User table Member_Type = ‘Inst’ or ‘Ind” depending on whether Membership_Class is ‘Institution’ or ‘Individual’ respectively Member_UserName = User_UserName Member_Since = User_Member_Since Member_EnteredBy = the Web Server’s REMOTE_USER value If Membership_Class is not ‘Registered’ and any of Upgrade_toPPP, Upgrade_toDB, Upgrade_toVirtualDomain, Upgrade_toSSL, Upgrade_toListserver, Upgrade_toAliases, Upgrade_Quota1, Upgrade_Quota2, Upgrade_Quota3 are True or not equal to ‘0’, create a new record in the Upgrade_Request table inserting these values into the record. Unless Membership_Class is ‘Registered’, insert a new record into the Invoice table with the following values: Invoice_Date is the current Timestamp Invoice_Medium = ‘Web’ Invoice_EnteredBy = REMOTE_USER and retrieve the Invoice_Number of this new record Insert a new record in the Invoice_Item table with the current Invoice_Number and User_Number. If Membership_Class is ‘Institution’ then the Item_Description should say ‘Institutional Annual Membership’ and the Item_Amount is the value of the Sys_Inst_Mem_Price. Otherwise, the Item_Description should say ‘Individual Annual Membership’ and the Item_Amount is the value of the Sys_Ind_Mem_Price. For each of the upgrade options listed in step 9 above where the option is not 0 or is “False”, insert a new record in the Invoice_Item table with an appropriate description and the value of the option field multiplied by the corresponding value from the System Defaults table. Calculate the total cost of the Invoice by taking the sum of all Invoice_Item records for this particular Invoice_Number and put this value in the Invoice_Amount field for the corresponding Invoice. Display the User Acceptance agreement based on the contents of the accept.tmpl page created by the web designers. Users will be instructed to print out this form and send it with any required documentation to the office. If Membership_Class is not Registered, append the Invoice information to the User Acceptance agreement created above using the format supplied in the invoice.tmpl file.
Possible Exit Conditions and Return Values	The user supplied Member_UserName is not valid or not unique. An error message informing the user of the nature of the problem is displayed on the returned HTML page and the form in the user/apply.html page is recreated and repopulated with the current values. The user is invited to pick a different UserName and resubmit the form. The user supplied Initial_Password is not valid or not sufficiently hard. An error message informing the user of the specific failure of the password is displayed on the returned HTML page and the form in the user/apply.html page is recreated and repopulated with the current values. The user is invited to pick a different InitialPassword and resubmit the form.
Sign Off by:	Project Manager & Membership Committee or Board Designate

user/login.cgi

Procedure Model Type: ( )Web Page ( X )CGI Script ( )Shared Library ( )System API Name: user/login.cgi Assigned to: Reference:
Description	This script creates a form to which the user enters their username and password, validates the information against the system records and if the user is authenticated, sets up a set of credentials for the user’s current session.
Implementation Skills	PERL, CGI, SQL
Parameter List	QueryString contains the URL (without the host portion) to which the user is redirected upon a successful authentication
Called By:	user/upgrade.html user/myacct.html
Can Call:	lib/Login.pm user/upgrade.cgi user/myacct.cgi user/index.html
Function Description	The login.cgi script queries the user for a username and password combination. For users, the default access_level is “0”.[1] The username is then sent to the auth_user command. If the user is successfully validated according to the auth_user command, the Login.pm’s constructor method is called and a Login object is returned. This Login object is used to create a new cookie called Login with the value “<username>:<access_level>:<session_token> and a 1 hour expiry period. This cookie is returned to the user’s browser. If successful, the user is redirected to the URL constructed from the relative path and filename contained within the QueryString variable. Otherwise, the user is returned to the login.cgi page again with the appropriate error message displayed. The user is also given a link to go to the user/index.html page.
Possible Exit Conditions and Return Values	A successful return from the auth_user command will redirect the user to the URL constructed from the relative path and filename passed through the QueryString variable (this value is relative in that it is missing the host and domain portion of a fully formed URL). An unsuccessful return from the auth_user command should return the user to another invocation of the login.cgi script and display the relevant error message. The user is always given the option of going to the user/index.html page or to the GPFN main page.
Sign Off by:	Project Manager

[1] The Access_Level value is included so that access texture can be incorporated in the future when different users and different volunteers can be given different levels of access to the system.

user/upgrade.cgi

Procedure Model Type: ( )Web Page ( X )CGI Script ( )Shared Library ( )System API Name: user/upgrade.cgi Assigned to: Reference:
Description	This script shows the user the available system upgrades available to them. If the user selects any upgrades, an entry is added to the upgrade table so that the upgrades can be processed and applied to the users account.
Implementation Skills	PERL, CGI, SQL, Javascript
Parameter List
Called By:	user/index.html
Can Call:	lib/Login.pm lib/uname_test.pl vol/invoice.tmpl
Function Description	The script calls the Login.pm module’s getLogin method to see if a valid set of user credentials exist for this user. If getLogin returns a NULL value, the user is redirected to the user/index.html page. If the getLogin returns a session credential, the Login.pm module’s getUserName method is called to determine the username of the session’s owner. The list of available upgrades for the user is determined and displayed to the user using the following logic: If the User record associated with the UserName has no corresponding entry in the Member table, then the Upgrade_User-Ind and Upgrade_User-Inst radio button is displayed. Only one of these options can be selected by the user. Javascript should be used to ensure that the user cannot select any other upgrade option unless one of these radio buttons is selected. If the Upgrade_User-Ind or Upgrade_User-Inst radio button is selected, ask the user to enter a textfield of between 4 and 16 characters for the Upgrade_Username field. If a corresponding entry in the Member table exists for this user, and the Member_Type is “Individual”, a checkbox for Upgrade_ind-Inst is displayed. If the corresponding entry in the Services table for this User_Number does not have a value for Service_PPP_Access, or Service_PPP_Access = 0, then a checkbox for Upgrade_toPPP is shown. If the corresponding entry in the Member_Type is “Institution” or the checkbox “Upgrade_Ind-Inst” or the radio button “Upgrade_User-Inst” is selected above, and the corresponding entry in the Services table for this User_Number does not have a positive integer value in the Service_WebSite field, then display a checkbox for Upgrade_toWebSite and by default set it to “checked.” If there is a corresponding entry in the Member table for this User_Number, display the following checkboxes: Upgrade_toVirtualDomain Upgrade_toDB Upgrade_toListserver and collect the following information in a text field for each of these checked options: Upgrade_VirtualDomainName Upgrade_DBName Upgrade_ListserverName If there is a corresponding entry in the Services table for Service_WebSite, or for Service_VirtualDomain, or the checkboxes for Upgrade_toVirtualDomain or Upgrade_toWebSite are selected above, display a checkbox for Upgrade_toSSL. If the corresponding entry in the Member_Type is “Institution” or the checkbox “Upgrade_Ind-Inst” or the radio button “Upgrade_User-Inst” is selected above, then display a checkbox for Upgrade_toAliases include two text fields for “Upgrade_AliasExtAddress” and “Upgrade_Alias_GPFNAddress” If there is a corresponding Member record for this User_Number, display three text fields with the current values for Service_Quota1, Service_Quota2, and Service_Quota3 for the corresponding Service table entry for this user. The labels for these fields should be constructed with meaningful labels from the Sys_Quota1_Mnt, Sys_Quota2_Mnt, and Sys_Quota3_Mnt fields. If there is no corresponding Member record for this User_Number and the Upgrade_User-Ind or Upgrade_User-Inst checkboxes are checked above, then display the default quotas from the Sys_Incl_Quota1, Sys_Incl_Quota2, and Sys_Incl_Quota3 fields as text fields. If a Username is requested in step 5 above, test this Username against the uname_test.pl library function. Collect the information and store all values in the respective fields of a new Upgrade_Request record. Insert a new record into the Invoice table with the following values: Invoice_Date is the current Timestamp Invoice_Medium = ‘Web’ Invoice_EnteredBy = REMOTE_USER and retrieve the Invoice_Number of this new record For each of the upgrade options selected above where the option is not 0 or False, insert a new record in the Invoice_Item table with an appropriate description and the value of the option field multiplied by the corresponding value from the System Defaults table. Calculate the total cost of the Invoice by taking the sum of all Invoice_Item records for this particular Invoice_Number and put this value in the Invoice_Amount field for the corresponding Invoice. Display the Invoice information using the format supplied in the invoice.tmpl file. Direct the user to print this invoice and reference it when sending in their cheque.
Possible Exit Conditions and Return Values	If getLogin returns a NULL value, the user is redirected to the user/index.html page. Otherwise, the user is supplied with an invoice of the total cost of their upgrades
Sign Off by:	Project Manager

vol/listapps.cgi

Procedure Model Type: ( )Web Page ( X )CGI Script ( )Shared Library ( )System API Name: vol/listapps.cgi Assigned to: Reference:
Description	This script lists the applications for accounts currently in a pending state and asks a volunteer to approve or delete the application
Implementation Skills	PERL, CGI, SQL
Parameter List
Called By:	vol/index.html vol/listapps.cgi
Can Call:	add_ppp() add_db(dbname) add_quota(mnt_point, Mb) add_ssl(virtual_domain_name) add_listserver(list_name) vol/index.html /index.html
Function Description	If the volunteer has selected the Delete button from a previous invocation of the form: Get the User_Number from the hidden field, then delete the User table record for this User, any Member table record for this user, any Upgrade_Request table record for this user where the Upgrade_ApprovedBy field is NULL, any Invoice table record where the Invoice_Number was in the Upgrade_Request record just deleted, and any Invoice_Item where the Invoice_Number is the Invoice_Number of the Invoice table record just deleted. If the volunteer has selected the Approve button from a previous invocation of the form, perform the following steps: Call the sys/add_account configuration command, passing it the username (User_UserName), password (User_InitialPassword), and if there is a Member table record with this User_Number, the Member_Type value for this User_Number (one of "Institution" or "Individual"). If there is no corresponding Member table record for this User_Number, then it will pass the value of "User" as the value of the Member_Type parameter. If the Upgrade_toPPP is True, then call the add_ppp configuration command to add this user to the radiusd server. If the Upgrade_toDB is True, then call the add_db command with the name from the Upgrade_DBName value and the Username of the user making the request passed as parameters. If the Upgrade_Quota1 is greater than 0, then call the add_quota command with the parameters Sys_Quota1_Mnt, the value of the Upgrade_Quota1 multiplied by 1024, and the user’s Username who is making the request. Repeat this step for Quota2 and Quota3. If Upgrade_toVirtualDomain is True, then call add_virtualdomain with the name from the Upgrade_VirtualDomainName and the user’s Username and Groupname passed as parameters. The Groupname should be set to “users”, the default UNIX user group for new users. If Upgrade_toSSL is True, then call add_ssl with the value of the Service_VirtualDomainName (if one exists) or the value of the Upgrade_VirtualDomainName field. If Upgrade_toAliases is True, then verify that the Upgrade_AliasGPFNAddress is not a UserName assigned to another user by checking whether it exists in the User or Member tables and that it is not an existing Alias for another user by checking whether it exists in the E-mail Alias table. If the alias is not assigned, then call the add_alias command with the values from the Upgrade_AliasExtAddress and Upgrade_AliasGPFNAddress as parameters. If Upgrade_toListserver is True, then call the add_listserver command with the name from the Upgrade_ListserverName and the user’s Username as parameters. Update the User table record, the Upgrade table record, the Member table record and the Services table record by inserting the value of the REMOTE_USER variable into the User_EnteredBy, Upgrade_ApprovedBy, Services_EnteredBy, and Member_EnteredBy fields. Set the User_IsActive field to “Active” from “Pending”. Set the User_ExpiryDate to December 31 of the current calendar year. Set the User_Status_Msg to “User account approved: <timestamp>” where timestamp is the current date. If the User is a member, then ensure that a record in the Services table exists for this user, even if that record contains only the default values for each field (i.e. the member has not upgraded to any additional services). Create a new receipt table record with the value of the Invoice_Number matching this User_Number, the User_Number, the current timestamp as the Receipt_Date, and the values from the CGI form for the values of Receipt_Amount, and Receipt_Payment_Type and REMOTE_USER as the Receipt_Entered_By. For all invocations of the script including the first: Select all records in the User table where the User_IsActive field = “Pending” For each record found in step 1, list the following information in a formatted table for each record. Each table should contain an HTML form with a hidden field containing the User_Number. Display the User_FirstName, User_LastName, User_Initial, User_Salutation, User_Organization (if exists), User_Title (if exists), User_StreetAddress1, User_StreetAddress2 (if exists), User_City, User_Province, User_Country, User_PostalCode, User_HomePhone (if exists), User_WorkPhone (if exists), and User_Age. If any of the required fields listed in the specifications for user/apply.html are left blank, a warning message should be displayed to the volunteer. In addition to the above fields, if a record exists in the Member table with this same User_Number perform the following additional steps: Check if there is a record in the Upgrade table for this User_Number where Upgrade_ApprovedBy is NULL. If there is, display a series of checkboxes and textfields listing the following fields from that table: Upgrade_toPPP (checkbox) Upgrade_toDB (checkbox) and show Upgrade_DBName (textfield) if Upgrade_toDB is True Upgrade_Quota1 (textfield) Upgrade_Quota2 (textfield) Upgrade_Quota3 (textfield) Upgrade_toVirtualDomain (checkbox) and show Upgrade_VirtualDomainName (textfield) if Upgrade_toVirtualDomain is True Upgrade_toSSL (checkbox) Upgrade_toAliases (textfield) and show Upgrade_AliasExtAddress (textfield) and Upgrade_AliasGPFNAddress(textfield if Upgrade_toAliases is an integer > 0 Upgrade_toListserver (checkbox) and Upgrade_ListserverName (textfield) if Upgrade_toListserver is True Get the Invoice table record with this User_Number and display the Invoice_Date and Invoice_Amount. Display a textfield named Receipt_Amount and a radio button array named Receipt_Payment_Type with values “Cash”, “Cheque”, “In-Kind”, “Visa”, or “MasterCard”. Display a “Approve” Submit Button and a “Delete” Submit Button for each Form.
Possible Exit Conditions and Return Values	If there are no pending applications, the list should be empty and volunteers can click a link to return to vol/index.html or the GPFN home page. Any application from the list can be left it is current pending state, deleted from the system, or approved.
Sign Off by:	Project Manager

vol/listupgrades.cgi

Procedure Model Type: ( )Web Page ( X )CGI Script ( )Shared Library ( )System API Name: vol/listupgrades.cgi Assigned to: Reference:
Description	This script lists the upgrades for existing accounts where an unapproved Upgrade_Request table record exists.
Implementation Skills	PERL, CGI, SQL
Parameter List
Called By:	vol/index.html vol/listupgrades.cgi
Can Call:	lib/add_alias lib/change_username Prototype-User (non-login account profile) Prototype-Ind (non-login account profile) Prototype-Inst (non-login account profile) add_ppp() add_db(dbname) add_quota(mnt_point, Mb) add_ssl(virtual_domain_name) add_listserver(list_name) vol/index.html /index.html
Function Description	If the volunteer has selected the Delete button from a previous invocation of the form: Get the User_Number from the hidden field, then delete the corresponding Upgrade_Request record, and update the corresponding User table User_Status_Msg with the string “Upgrade request declined on <date> by <REMOTE_USER> because: <Delete_Reason>.” where the appropriate values are inserted into the variables. Delete the corresponding record in the Invoice table and Invoice_Item table for this Upgrade_Request. If the volunteer has selected the Approve button: If Upgrade_User-Ind or Upgrade_User-Inst fields are True and no Member table record exists for this User_Number: insert a new record in the Member Table, setting the User_Number to User_Number, Member_Since to today’s date, Member_EnteredBy to REMOTE_USER, Member_UserName to the value of UserName supplied from the form, and the Value of Member_Type to “Institution” in the case of a Upgrade_User-Inst request or “Individual” for a Upgrade_User-Ind request. Call the add_alias command with parameters User_UserName as the old address and Member_UserName as the new address to map to. Call the change_username command to rename the user’s home directory and alter the appropriate entries in the /etc/password and /etc/shadow files. Call the edquota command with parameter “Prototype-Ind” or “Prototype-Inst” depending on the value of the Member_Type field. If there is a corresponding record in the Member table for this User_Name: If the Upgrade_toPPP is True, then call the add_ppp configuration command to add this user to the radiusd server. If the Upgrade_toDB is True, then call the add_db command with the name from the Upgrade_DBName value and the Username of the user making the request passed as parameters. If the Upgrade_Quota1 is greater than 0, then call the add_quota command with the parameters Sys_Quota1_Mnt, the value of the Upgrade_Quota1 multiplied by 1024, and the user’s Username who is making the request. Repeat this step for Quota2 and Quota3. If Upgrade_toVirtualDomain is True, then call add_virtualdomain with the name from the Upgrade_VirtualDomainName and the user’s Username and Groupname passed as parameters. The Groupname should be set to “users”, the default UNIX user group for new users. If Upgrade_toSSL is True, then call add_ssl with the value of the Service_VirtualDomainName (if one exists) or the value of the Upgrade_VirtualDomainName field. If Upgrade_toAliases is True, then verify that the Upgrade_AliasGPFNAddress is not a UserName assigned to another user by checking whether it exists in the User or Member tables and that it is not an existing Alias for another user by checking whether it exists in the E-mail Alias table. If the alias is not assigned, then call the add_alias command with the values from the Upgrade_AliasExtAddress and Upgrade_AliasGPFNAddress as parameters. If Upgrade_toListserver is True, then call the add_listserver command with the name from the Upgrade_ListserverName and the user’s Username as parameters. Update the Upgrade table record and the Services table record by inserting the value of the REMOTE_USER variable into the User_EnteredBy, Upgrade_ApprovedBy and Services_EnteredBy fields. Create a new receipt table record with the value of the Invoice_Number matching this User_Number, the User_Number, the current timestamp as the Receipt_Date, and the values from the CGI form for the values of Receipt_Amount, and Receipt_Payment_Type and REMOTE_USER as the Receipt_Entered_By For all invocations of the script including the first: Select all records in the Upgrade_Request table where the matching record in the User table with the same User_Number does not have User_IsActive = “Pending” For each record found in step 1, list the following information in a formatted table for each record. Each table listed in step 2 should contain an HTML form with a hidden field containing the User_Number. Display the User_FirstName, User_LastName, User_Initial, User_Salutation, User_Organization (if exists), User_Title (if exists), User_StreetAddress1, User_StreetAddress2 (if exists), User_City, User_Province, User_Country, User_PostalCode, User_HomePhone (if exists), and User_WorkPhone (if exists). In addition to the above fields, display the following additional values: Upgrade_User-Ind or Upgrade_User-Inst (as a radio button) Upgrade_toPPP (checkbox) Upgrade_toDB (checkbox) and show Upgrade_DBName (textfield) if Upgrade_toDB is True Upgrade_Quota1 (textfield) Upgrade_Quota2 (textfield) Upgrade_Quota3 (textfield) Upgrade_toVirtualDomain (checkbox) and show Upgrade_VirtualDomainName (textfield) if Upgrade_toVirtualDomain is True Upgrade_toSSL (checkbox) Upgrade_toAliases (textfield) and show Upgrade_AliasExtAddress (textfield) and Upgrade_AliasGPFNAddress(textfield if Upgrade_toAliases is an integer > 0 Upgrade_toListserver (checkbox) and Upgrade_ListserverName (textfield) if Upgrade_toListserver is True Get the Invoice table record with this User_Number and display the Invoice_Date and Invoice_Amount. Display a textfield named Receipt_Amount and a radio button array named Receipt_Payment_Type with values “Cash”, “Cheque”, “In-Kind”, “Visa”, or “MasterCard”. Get the Invoice table record with this User_Number and display the Invoice_Date and Invoice_Amount. Display a textfield named Receipt_Amount and a radio button array named Receipt_Payment_Type with values “Cash”, “Cheque”, “In-Kind”, “Visa”, or “MasterCard”. Display a textfield named “Delete_Reason”. Display a “Approve” Submit Button and a “Delete” Submit Button for each Form.
Possible Exit Conditions and Return Values	If there are no pending applications, the list should be empty and volunteers can click a link to return to vol/index.html or the GPFN home page. Any application from the list can be left it is current pending state, deleted from the system, or approved.
Sign Off by:	Project Manager

vol/geninvoice.cgi

Procedure Model Type: ( )Web Page (X)CGI Script ( )Shared Library ( )System API Name: vol/geninvoices.cgi Assigned to: Reference:
Description	This script taking parameters from the form on invoice.html generates invoices or statements for one or all system users
Implementation Skills	PERL, CGI, SQL
Parameter List	Invoice_Count User_UserName Type_Switch Medium_Switch
Called By:	vol/invoices.html vol/geninvoices.cgi
Can Call:	vol/index.html
Function Description	Depending on the values of the Type_Switch and Invoice_Count parameters, create a temporary directory named after the current process_id in which to store the following generated invoices or statements. Only one of the following six steps will be used for each invocation of this script: If Type_Switch = ‘NewInvoice’ and Invoice_Count = ‘all’, first ensure that the Sys_Last_Annual_Cycle is no more than 16 months after the current date[1]. If this test is successful, then get a list of all records in the User table where User_IsActive = ‘Active’ and User_Expiry_Date is less than the Sys_Last_Annual_Cycle. For each of these User records, create a new Invoice record, inserting the User_Number as the foreign key, the current date as the Invoice_Date, the Invoiced_Medium as the value of the Medium_Switch field, and the Invocie_EnteredBy as the value of REMOTE_USER. If the User IsMember field = 0, create a new invoice for this user. This Invoice should have a single Invoice_Item with Item_Amount = Sys_Reg_User_Price and Item_Description = “Renewal of Free Internet Account”.[2] If the User_Is_Member field= 1, denoting that the user is a member, then determine if the User is an Individual or Instutional member by querying the Member table for this user and create a new Invoice record with an Invoice_Item with Item_Description of either “Institutional Membership Renewal” or “Individual Membership Renewal” and an Item_Amount of either “Sys_Ind_Mem_Price” or “Sys_Inst_Mem_Price” respectively. If the User_Is_Member field = 1 and the user has a corresponding record in the Services table, for each service listed in the Service Table, multiply any non-zero value by the respective Price in the System_Defaults table and create a new Invoice_Item record with this product in the Item_Amount field and the Service Description in the Item_Description field, and update the Invoice_Number and User_Number. Once the Membership and all Services have been invoices for a user, obtain the sum of all Invoice_Item entries for this Invoice_Number and put this value in the Invoice_Amount field Increment the sys_Last_Annual_Cycle by 1 year to be December 31 of the end of the current billing cycle. If Type_Switch = ‘NewInvoice’ and Invoice_Count = ‘1’, get the User_UserName value from the CGI script and query the User table to get the corresponding User_Number for this UserName. For this User_Number, create a new Invoice record, inserting the User_Number as the foreign key, the current date as the Invoice_Date, the Invoiced_Medium as the value of the Medium_Switch field, and the Invocie_EnteredBy as the value of REMOTE_USER. If the User IsMember field = 0, create a new invoice for this user. This Invoice should have a single Invoice_Item with Item_Amount = Sys_Reg_User_Price and Item_Description = “Renewal of Free Internet Account”. If the User_Is_Member field= 1, denoting that the user is a member, then determine if the User is an Individual or Instutional member by querying the Member table for this user and create a new Invoice record with an Invoice_Item with Item_Description of either “Institutional Membership Renewal” or “Individual Membership Renewal” and an Item_Amount of either “Sys_Ind_Mem_Price” or “Sys_Inst_Mem_Price” respectively. For each service listed in the Service Table, multiply any non-zero value by the respective Price in the System_Defaults table and create a new Invoice_Item record with this product in the Item_Amount field and the Service Description in the Item_Description field, and update the Invoice_Number and User_Number. Once all Services have been invoices for the user, obtain the sum of all Invoice_Item entries for this Invoice_Number and put this value in the Invoice_Amount field. Once the Membership and all Services have been invoices for the user, obtain the sum of all Invoice_Item entries for this Invoice_Number and put this value in the Invoice_Amount field. If Type_Switch = ‘ExistingInvoice’ and Invoice_Count = ‘all’, get a list of all invoices from the Invoice_Table where there is no corresponding Receipt table entry and where ‘User_IsActive = ‘Active’. If Type_Switch = ‘ExistingInvoice’ and Invoice_Count = ‘1’, get the User_UserName value from the CGI script and query the User table to get the corresponding User_Number for this UserName. Get a list of all invoices from the Invoice_Table where there is no corresponding Receipt table entry and where the Invoice table User_Number is the current User_Number. If Type_Switch = ‘Statement’ and Invoice_Count = ‘all’, get a list of all Invoices and Receipts for each User where User_IsActive = ‘Active’. Format each statement using the stmt.tmpl template file such that all invoice and receipt entries are combined and then sorted in an oldest-date-first list. If Type_Switch = ‘Statement’ and Invoice_Count = ‘1’, get a list of all Invoices and Receipts for the User_Number corresponding to the User_UserName value. Format the statement using the stmt.tmpl template file such that all invoice and receipt entries are combined and then sorted in a oldest-date-first list. Regardless of which of the above six steps was selected, get the value of the Medium_Switch parameter: If the Medium_Switch = ‘E-mail’ format each file in the temporary directory created above as an e-mail message and send the statement or invoice via e-mail to <User_UserName>@gpfn.ca. Delete each temporary file after it is sent. If the Medium_Switch = ‘Screen’, format each file in the temporary directory created above as an HTML table, formatting it according to the invoice.tmpl or statement.tmpl file and then zipping it and then inserting a link in the returned page so the volunteer can download the file using a HTTP transport. Delete each temporary file after it is incorporated into the new HTML page. Delete the temporary directory created above.
Possible Exit Conditions and Return Values	The script should always return successfully
Sign Off by:	Membership Committee or board designate

[1] We don’t mind invoices going out in September for the coming year, but let’s make sure that we don’t have two volunteers thinking this way or we’ll be billing people for two years down the road.

[2] This requirement is intended to allow the Free-Net to query existing registered users to determine if they still want their free e-mail and dial-up account. The invoice should have some information for the user to either print the invoice, sign it and send it in, or else e-mail a confirmation that they want to keep their account.

vol/receipts.cgi

Procedure Model Type: ( )Web Page (X)CGI Script ( )Shared Library ( )System API Name: vol/receipts.cgi Assigned to: Reference:
Description	This script gets a list of all unpaid invoices and displays them to the volunteer so that the volunteer can apply receipts against them.
Implementation Skills	PERL, CGI, SQL
Parameter List
Called By:	vol/index.html vol/receipts.cgi
Can Call:	vol/index.html
Function Description	If the script has been called by a previous invocation of this same script as determined by the value of the Submit button being “Apply Receipt”: Create a new Receipt record with the values of the Invoice_Number hidden field, the User_Number for this invoice, the Receipt_Date being the current date, the Receipt_Amount being the amount entered from the CGI form, the Receipt_Payment_Type being the value entered from the CGI form, and the Receipt_EnteredBy field being set to REMOTE_USER. If the sum of a Receipt_Amounts in the Receipt table where the Invoice_Number corresponds to the Invoice_Number passed through the CGI form is equal to or greater than the value of the Invoice record’s Invoice_Amount for this Invoice_Number, then set the User_Expiry_Date one year past its current date. (i.e. the Invoice has been paid in full). For all invocations through this script, even the first, perform the following steps: Get a list of all Invoices from the Invoice table where the User_IsActive = ‘Active’ of the corresponding User_Number and where the sum of all Receipt_Amounts in the Receipt table with this Invoice_Number is less than the Invoice_Amount (i.e. the invoice has not been fully paid). Display a table to the volunteer. For each Invoice returned in step 1, create a row in a table that contains a form. Set the Invoice_Number as a hidden field within each form. Each row will also include: the User’s first and last name, the User’s username, and the value of the User_Since, User_Expiry_Date, and the value of the corresponding Member_Type field in the corresponding Member table. Also display the Invoice_Date, the Invoiced_Medium, the Invoice_Amount, and the sum of any Receipt_Amounts already applied against the Invoice. Present a textfield with the default value set to the difference of the Invoice_Amount less the sum of all Receipt_Amounts applied against this Invoice. Display a radio button array with the values “Cash”, “Cheque”, “In-Kind”, “Visa”, and “MasterCard”. Each row will also include a submit button with the name “Apply Receipt”
Possible Exit Conditions and Return Values	The script should always return successfully. If no outstanding invoices exist, an empty list should be presented. Volunteers can always click on a link to take them to the vol/index.html or GPFN main page.
Sign Off by:	Membership Committee or board designate

Shared Library Procedures

lib/uname_test.pl

Procedure Model Type: ( )Web Page ( )CGI Script (X)Shared Library ( )System API Name: lib/uname_test.pl Assigned to: Reference:
Description	This script verifies that a username passed as a string to the function would be a good username. The test of goodness requires that the proposed username is unique to the system (i.e. no existing user has this name), and that the username is comprised of only alphabetic characters, numbers, underscores and dots (period), and that the username is between 4 and 16 characters long. For the purpose of the test, uppercase and lowercase characters are equivalent so that if the user has chosen a username of upper-case characters, these characters will be replaced with their lower-case equivalents.
Implementation Skills	PERL
Parameter List	String containing the proposed username
Called By:	user/validate.cgi user/upgrade.cgi lib/uname_generate.pl
Can Call:
Function Description	Verify the appropriateness and uniqueness of the proposed username by performing the following steps: Check that the username is between 4 and 16 characters in length and contains only characters, digits, underscores and dots (periods). If it fails this test, exit this function and return an appropriate error description. Convert the proposed username to all lowercase letters. Check that the username is unique within the system. If this test fails, exit the function and return an appropriate error description. This test of uniqueness is met if: There is no existing entry in the /etc/password file with the same username There is no existing entry in the /etc/mail/aliases file such that the proposed username was a previous system username that has since been remapped to a new username. There is no other entry in the User table or Member table with this username such that the same username is in a pending state awaiting another user’s agreement or remittance. Return a null length string if the proposed username is acceptable to the system.
Possible Exit Conditions and Return Values	If the username is not appropriate, a descriptive error message is returned as a scalar variable. If the username is appropriate, the function returns a null length string.
Sign Off by:	Project Manager.

lib/uname_generate.pl

Procedure Model Type: ( )Web Page ( )CGI Script (X)Shared Library ( )System API Name: lib/uname_generate.pl Assigned to: Reference:
Description	This function returns a string containing the next available sequential username following the format aannn where “a” denotes an alphabetic, lowercase character and “n” denotes a digit. For example, if the last username assigned by this function was aa999, the function will test that ab000 is not assigned and if it is free, will assign it. Otherwise, the function will test for ab001 and so on.
Implementation Skills	PERL
Parameter List	none
Called By:	user/validate.cgi
Can Call:	lib/uname_test.pl /usr/local/csuite/etc/lastacct
Function Description	Open the /usr/local/csuite/etc/lastacct file if one exists. If this is the first time the script is ever called, this file will have to be created. The contents of the lastacct file should include the last created username. If it does not, assume that the lastacct has value “aa000.” Read this username into a variable and increment it according to the algorithm described in the description section above. Write this new incremented value back to the lastacct file, deleting all previous content. Test this newly incremented value using the uname_test.pl function. If this new username passes this test return this new username to the calling procedure. Otherwise, repeat steps 2 and 3 until this test is successful.
Possible Exit Conditions and Return Values	The function returns the value of the next available sequentially assigned username as a scalar value.
Sign Off by:	Project Manager

lib/pw_check

Procedure Model Type: ( )Web Page ( )CGI Script (X)Shared Library ( )System API Name: lib/pw_check Assigned to: Reference:
Description	This function takes a string parameter and runs it against the system pw_check utility to see if it is a sufficiently strong password. If not, the function returns a string describing the weakness(es) of the password.
Implementation Skills	C
Parameter List	password- a string containing the password string to test
Called By:	user/validate.cgi
Can Call:	crack.h
Function Description	#include <stdio.h> #include <stdlib.h> #include <crack.h> int main(int argc, char argv[]) { int i; char pw_check; char* password; char* dict_path = “/usr/lib/cracklib_dict”; char* null_string = “”; char* bad_usage = "Usage: pw_check [password]"; if (argc != 2) { fputs(bad_usage,stdout); return (-1); } password = argv[1]; pw_check = FascistCheck(password, dict_path); if (pw_check != NULL) fputs(pw_check,stdout); else fputs(null_string,stdout); exit(0); } Usage within a PERL or Shell Script: $output=`pw_check([password])`; if ($output eq “”) { # password is good } else { # password is bad. Reason is stored in $output }
Possible Exit Conditions and Return Values	The program returns a –1 if an insufficient number of parameters were passed to the command. The description of the proper way to call the program should be passed through to the calling routine using the stdout handle. Check the contents of the $output variable in the above function description example. The program returns a 0 if the program is properly called. If the password is sufficiently strong, then an empty string is passed back through the stdout handle. Otherwise, a text string describing the problems with the password are listed. Since multiple problems can exist, these lines will be separated with a newline character (“\n”).
Sign Off by:	Project Manager

lib/Login.pm

Procedure Model Type: ( )Web Page ( )CGI Script (X)Shared Library ( )System API Name: lib/Login.pm Assigned to: Reference:
Description	This module manages login sessions for the system. Its public methods are called by CGI scripts to determine if the user is properly authenticated on the system and has currently valid credentials. The Constructor assumes that the user has been authenticated by the login.cgi script. As such, it accepts the call to create the session token, but does no additional checks on the authenticity of the user.
Implementation Skills	PERL, SQL, MySQL
Parameter List	Username, access_level
Called By:	user/login.cgi user/upgrade.cgi user/myacct.cgi user/quota.cgi user/passwd.cgi user/forward.cgi user/history.cgi user/filter.cgi
Can Call:	Http_Sessions database.
Function Description	HTTP_Sessions database Sessions table: +-------------+---------------+------+-----+---------+-------+ \| Field \| Type \| Null \| Key \| Default \| Extra \| +-------------+---------------+------+-----+---------+-------+ \| User_Name \| varchar(20) \| \| PRI \| \| \| \| Session_Tok \| varchar(32) \| \| \| \| \| \| Access_Level\| int \| \| \| 0 \| \| \| TimeStamp \| timestamp(14) \| YES \| \| NULL \| \| +-------------+---------------+------+-----+---------+-------+ Constructor(UserName, Access_Level) method: Take the username and access_level from the parameter list passed to the function. Open the sessions database and delete any previous entry for this same username. Create a session token by MD5 base64 encoding the current timestamp. Insert a new record into the Sessions table with this User_Name, Session_Token, and Access_Level. Populate and return a Login object with the User_Name, Session_Token and Access_Level. This object is then used by the calling program to send a Login cookie back to the user’s browser using the format: “<username>:<access_level>:<session_token> getLogin() method: Get a reference to the CGI query object and extract the Login cookie from this object. If no cookie exists, return a null Login object. Otherwise, split the Login cookie using the colons into its username, access_level and session_token values. Query the Sessions table for a matching token and if one exists populate a new Login object with the values from the database. Otherwise, return a null Login object. getUserName(Login) method: Using the Login object passed as a parameter, return the Username string property of the object. getAccessLevel(Login) method: Using the Login object passed as a parameter, return the Access_Level integer property of the object. destroy(UserName) method: Delete any record in the Sessions table with this UserName and nullify any cookie stored on the browser by returning a new Login cookie with an empty string for its value.
Possible Exit Conditions and Return Values	A Login object with undefined properties indicates that the system failed to find any credentials for this user. This test is usually performed by using the getLogin() method to get a Login object and then calling the getUserName(Login) method with the Login object returned by the getLogin method. If the getUserName method returns an undefined value, then the credentials do not exist or there is a system problem. Note that this class does not test for the age of a set of credentials although such a test can be included by having the getLogin method test the age of the session token by looking at the timestamp value in the Sessions table.
Sign Off by:	Project Manager.

lib/auth_user

Procedure Model Type: ( )Web Page ( )CGI Script (X)Shared Library ( )System API Name: lib/auth_user Assigned to:
Description	This suid program takes the username and password and returns a 0 if the username and password match the system password for the stated user. Any other return code indicates an error.
Implementation Skills	C, PAM
Parameter List	Username and password as string values
Called By:	user/login.cgi
Can Call:	PAM system libraries
Function Description	Example of a proper function call from a calling PERL script: output=`/usr/local/csuite/lib/auth_user $user $passwd `; /*************************************************** Library functions to interact with the Linux-PAM modules in order to update a user's password on the system. Make sure you add the following lines to the pam.conf file (or equivalent): cs_password auth required /lib/security/pam_unix_auth.so cs_password account required /lib/security/pam_unix_acct.so cs_password password required /lib/security/pam_unix_passwd.so cs_password session required /lib/security/pam_unix_acct.so Author: Daryle Niedermayer (dpn) daryle@gpfn.ca Date: 2002-06-17 ***************************************************/ #include <stdio.h> #include <stdlib.h> #include <security/pam_appl.h> #include <security/pam_misc.h> #define CS_BAD_DATA -2 #define CS_BAD_USAGE -1 #define CS_SUCCESS 0 #define COPY_STRING(s) (s) ? strdup(s) : NULL / DEFINE STATIC EXTERNAL STRUCTURES AND VARIABLES SO THAT THEY ONLY HAVE SCOPE WITHIN THE METHODS AND FUNCTIONS OF THIS SOURCE FILE / static char service_name = "cs_password"; static char* user; static char* old_password; static char* new_password; static int PAM_conv (int, const struct pam_message, struct pam_response, void); static struct pam_conv PAM_converse = {PAM_conv, NULL}; /********************************************** PAM Conversation function *********************************************/ static int PAM_conv ( int num_msg, const struct pam_message msg, struct pam_response *resp, void appdata_ptr) { int replies = 0; struct pam_response reply = NULL; reply = malloc(sizeof(struct pam_response) num_msg); if (!reply) return PAM_CONV_ERR; for (replies = 0; replies < num_msg; replies++) { if (! strcmp(msg[replies]->msg,"Password: ")) reply[replies].resp = COPY_STRING(old_password); if (! strcmp(msg[replies]->msg, "(current) UNIX password: ")) reply[replies].resp = COPY_STRING(old_password); } resp = reply; return PAM_SUCCESS; } /********************************************** MAIN PROCEDURE **********************************************/ int main(int argc, char argv[]) { /* DEFINITIONS / pam_handle_t pamh = NULL; int retval; char* pw_check; char* dict_path = "/usr/lib/cracklib_dict"; /* DETERMINE IF VARIABLE COUNT IS CORRECT / if (argc != 3) { printf("Usage: auth_user <USER> <PASSWORD>\n"); exit (CS_BAD_USAGE); } / PARSE PARAMETERS FROM INPUTS / user = argv[1]; old_password = argv[2]; if (!(user && old_password && strlen(user) && strlen(old_password))) exit (CS_BAD_DATA); / GET A HANDLE TO A PAM INSTANCE / retval = pam_start(service_name, user, &PAM_converse, &pamh); / IS THE USER REALLY A USER? / if (retval == PAM_SUCCESS) retval = pam_authenticate(pamh, 0); else return retval; / IS USER PERMITTED ACCESS? / if (retval == PAM_SUCCESS) retval = pam_acct_mgmt(pamh, 0); else return retval; / CLEAN UP OUR HANDLES AND VARIABLES */ if (pam_end(pamh, retval) != PAM_SUCCESS) pamh = NULL; else return retval; exit (CS_SUCCESS); }
Possible Exit Conditions and Return Values	This function returns a number of possible values: CS_BAD_DATA = -2 is returned if any of the username or passwords are null length strings or do not exist. CS_BAD_USAGE = -1is returned if an invalid number of parameters is passed to the function. CS_SUCCESS = 0 is returned if the function successfully authenticated the user with the supplied parameters. Any other positive integer indicates a PAM error. The meaning of the error value can be determined by referencing the /usr/include/security/_pam_types.h header file.
Sign Off by:	Project Manager

System Configuration Procedures

sys/add_account

Procedure Model Type: ( )Web Page ( )CGI Script ( )Shared Library (X)System API Name: sys/add_account Assigned to: Reference:
Description	This system configuration function runs with suid root permissions. It adds a new account to the system with the value of the username field passed in as a parameter, then sets the initial password on this account to the value of the password field passed in as a parameter. Finally, it uses the system edquota command to set the user quota on this new account to the value stored in the corresponding prototype account.
Implementation Skills	PERL, C
Parameter List	Username, password, and member_type.
Called By:	vol/listapps.cgi
Can Call:	/usr/bin/passwd /usr/sbin/useradd /usr/sbin/edquota -p prototype-user (non-login account profile) prototype-ind (non-login account profile) prototype-inst (non-login account profile)
Function Description	The script will be executed using suid root permissions. It will call the system useradd command passing it the username value contained in its parameters. It will call the system passwd command with parameters username and password. Call the system edquota -p command passing it the username value and, depending on the value of the Member_Type command, the "prototype-ind", "prototype-inst", or "prototype-user" account names.
Possible Exit Conditions and Return Values	If the user or system is unsuccessful in executing its parts, it will return a –1 if it is unable to invoke the useradd command, -2 if it is unable to set the password, and –3 if it is unable to set the disk quotas. If the alias is successfully created or replaced, the function returns a 0.
Sign Off by:	Project Manager

sys/add_alias

Procedure Model Type: ( )Web Page ( )CGI Script ( )Shared Library (X)System API Name: sys/add_alias Assigned to: Reference:
Description	This system configuration function reads the system /etc/mail/aliases file, checks that no current entry matching old_address exists and if one does exist, deletes it. It then adds a new entry mapping old_address to new_address and rebuilds the newaliases database. The function must NOT be allowed to alter any of the system aliases. Because editing the aliases file and rebuilding new alias databases are protected procedures, this function will need suid permissions.
Implementation Skills	PERL, C
Parameter List	old_address and new_address where old_address is the address to which mail is sent and new_address is the address to which mail is delivered.
Called By:	vol/listapps.cgi vol/listupgrades.cgi
Can Call:	/usr/bin/newaliases /etc/aliases log/csuite
Function Description	Open the /etc/aliases file for reading and check whether any existing mapping from old_address exists. If this mapping exists, verify whether it exists above the lines marked: ############################################## ## Lines below this line are managed by the ## ## /usr/local/csuite/sys/add_alias command. ## ## Do NOT edit aliases below this line. ## If the mapping exists above this section, return a –1 error. The mapping is a system mapping and cannot be altered by this script. If the mapping exists below the commented section, delete the entry from the /etc/aliases file. Enter the details of this deletion in the csuite log file. Add a new entry to the /etc/aliases file, inserting the entry alphabetically after the above comment section. The new entry should have the form: <old_address>: <tab><new_address> Enter the details of this insertion in the csuite log file. Run the /usr/bin/newaliases command to recompile a new aliases database.
Possible Exit Conditions and Return Values	If the user or system is attempting to create or replace a system alias, the function returns a –1. If the alias is successfully created or replaced, the function returns a 0.
Sign Off by:	Project Manager

sys/change_user

Procedure Model Type: ( )Web Page ( )CGI Script ( )Shared Library (X )System API Name: sys/change_user Assigned to: Reference:
Description	This function renames the user’s home directory from old_username to new_username, effecting this change in the system password and shadow files and adding a system alias mapping the old_username to new_username. Because of the permissions involved, this command must be set to suid root.
Implementation Skills	C
Parameter List	old_username, new_username
Called By:	vol/listupgrades.cgi
Can Call:	sys/add_alias /usr/sbin/usermod log/csuite
Function Description	Use the system’s usermod command to move the user’s home directory to the new location and move the login name to the new login name. Enter an entry in the log/csuite directory noting these changes. Call the add_alias command to add a new alias mapping from the old_username to the new_username. Return 0.
Possible Exit Conditions and Return Values	This function should always return 0.
Sign Off by:	Project Manager

sys/add_virtualdomain

Procedure Model Type: ( )Web Page ( )CGI Script ( )Shared Library (X )System API Name: sys/add_virtualdomain Assigned to: Reference:
Description	This function is a stub to add a new virtualdomain to the webserver configuration. It currently manages a manual workflow process but can be automated in the future.
Implementation Skills	PERL
Parameter List	Domainname, Username, Groupname
Called By:	vol/listapps.cgi vol/listupgrades.cgi
Can Call:	log/csuite
Function Description	E-mail the request to the webserver administrator to set up a new virtual domain. The root directory of the new virtualdomain and all child directories should be owned by the user given in the Username parameter and the group given in the Groupname parameter.
Possible Exit Conditions and Return Values	Currently, this function will always be successful (returning 0). In the future, it will return a –1 if the virtual domain name is already taken.
Sign Off by:	Project Manager

sys/add_ppp

Procedure Model Type: ( )Web Page ( )CGI Script ( )Shared Library (X )System API Name: sys/add_ppp Assigned to: Reference:
Description	This function is a stub to grant ppp access to a new or existing member. It currently manages a manual workflow process but can be automated in the future.
Implementation Skills	PERL
Parameter List	username
Called By:	vol/listapps.cgi vol/listupgrades.cgi
Can Call:	log/csuite
Function Description	E-mail the request to the system administrator to set up ppp access for a user. Log this entry to the log/csuite file
Possible Exit Conditions and Return Values	Currently, this function will always be successful (returning 0). In the future, it will return a –1 if ppp access is not permitted for some reason.
Sign Off by:	Project Manager

sys/add_db

Procedure Model Type: ( )Web Page ( )CGI Script ( )Shared Library (X )System API Name: sys/add_db Assigned to: Reference:
Description	This function is a stub to create a new database and provide read/write access to a new or existing member. It currently manages a manual workflow process but can be automated in the future.
Implementation Skills	PERL
Parameter List	Database_name, Username, Password
Called By:	vol/listapps.cgi vol/listupgrades.cgi
Can Call:	log/csuite
Function Description	E-mail the request to the system administrator to set up a new database with access for the user with the Username parameter. This user should have complete access with grant privileges to the database with the password supplied through the Password parameter. Log this entry to the log/csuite file
Possible Exit Conditions and Return Values	Currently, this function will always be successful (returning 0). In the future, it will return a –1 if the database creation failed for some reason.
Sign Off by:	Project Manager

sys/add_quota

Procedure Model Type: ( )Web Page ( )CGI Script ( )Shared Library (X )System API Name: sys/add_quota Assigned to: Reference:
Description	This function is a stub to add disk quota to a user. It currently manages a manual workflow process but can be automated in the future.
Implementation Skills	PERL, C
Parameter List	Mount_point, Mb to increase, Username
Called By:	vol/listapps.cgi vol/listupgrades.cgi
Can Call:	log/csuite /usr/sbin/setquota
Function Description	E-mail the request to the system administrator to add an additional number of Mb of file quota on the specified mount point for a user given in the parameter Username. Log this entry to the log/csuite file
Possible Exit Conditions and Return Values	Currently, this function will always be successful (returning 0). In the future, it will return a –1 if the setquota command fails for some reason.
Sign Off by:	Project Manager

sys/add_ssl

Procedure Model Type: ( )Web Page ( )CGI Script ( )Shared Library (X )System API Name: sys/add_ssl Assigned to: Reference:
Description	This function is a stub to add ssl access to a virtual domain. It currently manages a manual workflow process but can be automated in the future.
Implementation Skills	PERL, C
Parameter List	Virtual_domain
Called By:	vol/listapps.cgi vol/listupgrades.cgi
Can Call:	log/csuite
Function Description	E-mail the request to the system administrator to add an SSL enabled directory to the virtual domain specified in the parameters. Log this entry to the log/csuite file
Possible Exit Conditions and Return Values	Currently, this function will always be successful (returning 0). In the future, it will return a –1 if the configuration is not permitted for some reason.
Sign Off by:	Project Manager

sys/add_listserver

Procedure Model Type: ( )Web Page ( )CGI Script ( )Shared Library (X )System API Name: sys/add_listserver Assigned to: Reference:
Description	This function is a stub to add a new mailing list to the listserver. It currently manages a manual workflow process but can be automated in the future.
Implementation Skills	PERL, C
Parameter List	Listname, Username
Called By:	vol/listapps.cgi vol/listupgrades.cgi
Can Call:	log/csuite
Function Description	E-mail the request to the listserver administrator to add a new mailing list to the listserver with the specified name. Log this entry to the log/csuite file. Username should be added to the logging entry for audit and tracing purposes.
Possible Exit Conditions and Return Values	Currently, this function will always be successful (returning 0). In the future, it will return a –1 if the configuration is not permitted for some reason.
Sign Off by:	Project Manager