melbourne chapter

Last week I posted about the 2.2 version being released, the osCommerce guys have now just released a testing version of 3 to the public!

Here are some of the new features made available in this release:

• New object-oriented framework (alpha 1)
• New installation routine (alpha 1)
• register_globals and magic_quotes_gpc compatibility (alpha 1)
• New template structure implementation (alpha 1)
• Search-engine optimizations (alpha 1)
• Service modules (alpha 1)
• Checkout procedure cleanup (alpha 2)
• New language definitions implementation (alpha 2)
• Updated payment modules with post-transaction actions (alpha 3)
• Catalog front-end, administration tool, and installation routine combined (alpha 3)
• XHTML/CSS based default template layout for the catalog side (alpha 3)
• Multiple product images implementation (alpha 3)
• New action modules (alpha 3)

I haven’t had the chance to look at the update properly but the dev team say this update addresses security related issues and bug reports that exist in the released version. More info on the update is available on the osCommerce forums and the online documents
Get the update here: http://www.oscommerce.com/solutions/downloads

This year from the 6th to the 8th of December Melbourne will be hosting the annual Open Source Developers’ Conference (OSDC). The OSDC is an Australian run non-for-profit conference run by developers for developers on Open Source technologies. Talks and papers are mainly from people who write and use Open Source languages and are noted to be visited by many PHP/Python/Perl programmers. Talks range from introductory to deeply technical articles.

Currently the OSDC is requesting papers to be submitted for talks and the deadline is by July 12th 2006. You can view last years proposals here.

I am interested in attending a few different conferences over the next year and hope to attend this one and also the New York PHP conference next year.

March this year I reported a case where OSCommerce was not successfully passing shipping tax onto the final payment amount. I found that although the order total was indicated on the confirmation page, the amount processed by the Payment Module was always less the shipping tax amount! A quick diagnosis of the problem indicated that OSCommerce’s developers had intended to calculate once for output on the confirmation page, and then a second time for Payment processing. However, due to the incorrect inclusion order of source files the latter calculation would not complete before the transaction of the Payment Module began.

Resolving this bug is relatively straight forward (as always please backup, and use at own risk):


 
/*
$Id: checkout_process.php,v 1.128 2003/05/28 18:00:29 hpdl Exp $
 
osCommerce, Open Source E-Commerce Solutions
http://www.oscommerce.com
 
Copyright (c) 2003 osCommerce
 
Released under the GNU General Public Licensend
 
amended by Richard Lee
*/
 


CHANGE


$payment_modules->before_process();
 
require(DIR_WS_CLASSES . 'order_total.php');
$order_total_modules = new order_total;

TO


// make sure we run total's calculations first
$order_totals = $order_total_modules->process();
 
$payment_modules->before_process();


PKI (Public Key Infrastructure) is well known to security buffs. It involves the use of a public key to encrypt something, and can not be reused to decrypt. Instead, a private key kept secure by the intended recipient is used to decrypt. This allows the public key to be freely available online and useless for decrypting messages created with it. Originally (to my knowledge) it was first implemented by a guy who wrote PGP (Pretty Good Privacy). History asside, the PGP is a commercial application and GnuPG is an open source implementation. Both are interchangeable.
Because it is open source we often find it available on Linux hosting. This means that using GnuPG we can encrypt secure messages received by the server (not to the server, that can still be intercepted unless under HTTPS protocol). Keys can have varying strengths (2048bit for example) and have different types (e.g. RSA) with cipher/hash combinations (e.g. AES-256/SHA-2-256). Perfect for making some pretty damn secure messaging.

This requires you to have your public key added to your GnuPG Keychain that the webuser can access. A good example for getting GnuPG installed and having your keychain added is here. You typically can just send your public key chain in an email message to your hosting company and have them add it to their keychain. They will be friendly to add it.

You will need to know the directory to gpg bin on your hosting server, as well as the .gnupg keychain location to specify in your –homedir parameter. Your hosting company again will save you with this one.

So, as a simple example on the usage of GnuPG I will demonstrate by discussing a quick way of encrypting details received by form input:

$prefix = 'enc';
$command = '/usr/bin/gpg --always-trust --batch --no-secmem-warning --homedir /home/www/.gnupg -a -r "Cameron Manderson" -e';
$tmpFile = tempnam('/tmp', $prefix);
$pipe = popen("$command 2>&1 >$tmpFile", 'w');
if (!$pipe) {
unlink($tmpFile);
} else {
fwrite($pipe, $plainTxt, strlen($plainTxt));
pclose($pipe);
$fd = fopen($tmpFile, "rb");
$output = fread($fd, filesize($tmpFile));
fclose($fd);
unlink($tmpFile);
}

The idea behind the code above code is that we form a message assigned to the variable $plainTxt, and have it encrypted by the popen call, then have the encrypted details placed into $output. If you are using this to accept input from a user and encrypt it (such as encrypting credit card details and the like) you will want to ensure you are under a suffice level of HTTPS.
I have purchased a copy of PGP Desktop which allows me under a windows gui environment decrypt and view the contents of a message. This is great for end users because it allows them to easily decrypt a message using windows. It also can integrate into their mail application (such as Outlook or Thunderbird).

I thought I would discuss a quick overview on the structure to ACL for your applications. For initial background on ACL read this previous article first.

The implementation on ACL I have used in the past and appears in several different well known GNU applications is PHP Generic Access Control Lists (phpGACL). This library provides two main classes and an Administration Screen. The administration screen allows us a friendly way of managing our control lists, and the classes are used to check/modify them in our application. Overall I have found this package quite suitable for most situations.
Once installed, you will need to get familiar with the different terminology that is used.

First we must analyse the way that we need to set up our application. Typically we have many users with different group permissions. I like to use

- Developer
- Administrator
- Staff
- Public

These groups are groups of ARO or Access Request Objects. Therefore our 2Dimensional implementation is infact (ARO requests ACO). They are often the groups of system actors in your application, and represent the different objects/users making the requests. You can deal with groups of ARO’s or single ARO’s in your application. Your API calls will change slightly, my examples will explain as ARO groups.
How we manage the resources they wish to access can be either in a 2Dimensional (ARO requests this action) or 3D (ARO request this action on this object).

Both the ways of managing requires you to define our action/controlled object. These are called ACO or Access Controlled Objects. Typically I like to define a few sections of ACO’s, first being for the action being requested (in terms of MVC), and secondly any more fine-grained permissions, such as ‘Allow Edit’, ‘Allow Delete’, ‘Allow Hidden’ etc. Your ACO may end up being similar to:

Section: Actions
- login
- logout
- home
- documents
And another Section may manage specific more finegrained functionality on a particular operation:

Section: Documents
- edit
- add
- delete

In most situations this is more than enough for our small applications, and allows us to create well manageable applications, being able to create custom users/groups with specific permissions in our application, without requiring changes to our source code. As explained in my previous article, ACL allows us to make our security implementation extendable and manageable without requiring hundreds of updates to each of our source code files.

Now when we with to check a 2Dimensional request, we can do so with a simple ACL check; acl_check($resource, $group);

For our section ‘Actions’ I like to typically place this resource in our RequestProcessor, allowing us to have a ‘gatekeeper’ to whether the requested action can be performed by the current logged in user. This will ensure that every action is checked against the users permissions, before loading the Action to perform.

Our section ‘Documents’ would call specific checks to whether the user is allowed to perform a certain action in our Action class through again another set of ACL checks.

This situation becomes more complex when with have specific resources that the user wishes to manage, such as documents in a specific project. This becomes a 3Dimensional implementation that is when our ACO requests an ARO on a particular object. Yes I understand we are talking Object requests Object on an Object, and can come a bit complex, but the best is with an example. The 3rd Object is termed a AXO, or Access eXtension Object.

our AXO Section may look as follows:

Section: Projects
- project 1
- project 2
- project 3

This now allows us to further split down our requests so that our Document Management actions can be specific for a user in a particular project. Our ACL check becomes a little more complex, with having to specify a 3rd level.

Overall this implementation allows us to start to secure down what actions can be performed by our application users. We need to be conscious now to over-allow or over-complex our application for users as it will just mean more testing, training and explaining. Remember, just having ACL’s in your application does not make it more secure unless you use them correctly. You must be conscious of breaking down permissions, correctly verifying users and ensuring that you don’t just grant everything in your application.

We once had a challenge in our Linux Operating System class to use bash to connect to the Australian BOM website (Bureau of Meteorology) and extract the current temperature in Melbourne. The task was quite trivial and involved the use of grep, awk and sed to extract the information.

Listed on the BOM website are two pages that allow us to get the current temperature reading at various weather stations and also the weather headline.

I have provided the script as an example of a simple way to retrieve the information from the BOM website. It could be used with a crontab script setup to run every 5 minutes and can update a text file, which you could then use to display on your website.

This script can easily be re-written to extract all the weather forecasts and current temperatures for various australian weather stations. It would be a good idea to have this extended to be a public web-service. I had later rewrote this script to generate XML with complete conditions (warnings, wind direction etc) and not require wget. If I find it I will post it, I had just stumbled across this one in the attic.
Download the bash script here, please respect as GPL.

If you simply want the current weather temperature there is a free webservice located here:http://www.stanski.com/services/worldweather/weather.asmx?op=getMelbourneTemperature

I have had a fair bit of experience now with Payment Modules under osCommerce. I have used publicly available payment modules as well as writing my own (for Australian eSec/Securepay, Westpac Webadvantage and Mastercard Internet Gateway Services - MIGS).

I have to say that a lot of the modules aren’t correctly documented and often take the quickest approach to doing a problem, without considering future maintenance or implementing good industry practices. Overall the osCommerce package has, in my opinion, in general, become more of a nightmare than a solution for anything you want to do that slightly changes from the standard package they provide.

But instead of turning this into a “I am so over osCommerce” post I am going to discuss coding up a Payment Method that will suit the requirements of your client or your site.

The Payment Module

The payment module is a way of creating a custom hook point for handling payment by a specific means, such as accepting payment via PayPal or through an Online Credit Card Gateway. It is written flexible enough to cater for 98% of situations and has frameworked multilanguage support. A payment module is formed of two files, the Payment Module Language file as well as the Payment File Class.

The payment module language files are located in

“includes/languages/[english]/modules/payment” and should to correspond to the same name as your class file. It contains series of define(); calls to setup the various language requirements that you need.

The payment module class files are located in

“includes/modules/payment” and are typically named similar to “cc_via_whatever.php” or something more descriptive. This is the file that will handle our processing.

You will need to request from your payment gateway provider an integration guide. Any payment provider will be able to provide you this information and should provide sufficient support for you to diagnose the process.

The next step is to analyse the flow of the Payment Module Class. This is extremely important for you to understand as you will need to disect your payment integration into the correct functions of your Payment Class. Ensure that you protect your clients sensitive information and never rely on hidden form fields (!).
The order in which the payment module is executed occurs similar to below:

Constructor (function cc_via_whatever): Purpose is to initialise requirements of osCommerce. The variables that it wants you to configure include:

- $this->code = (same as your class file name prepend, eg, “cc_via_whatever”)
- $this->title = (Title of the payment module, EG “Payment Via Credit Card Facilities Online”, you will see this appear on your website frontend)
- $this->description = (a more verbose explaination of the payment module)
- $this->enabled = (This is very important to set true or false. I usually check to ensure all my Admin controlled variables are set before making this module enabled)
- $this->form_action_url = (Where to submit the form contents to once hit submit)
- $this->sort_order = (The sort order of this module in correspondance to others)

function update_status: Purpose it so check whether this payment module is available during runtime with an order.
Usually this method will analyse whether the payment module is valid within this clients zone. This is usually a generic call, so you can reference other example payment modules.

First Stage, Making Selection of the Payment Module

function javascript_validation: Purpose is to check the contents of the submitted payment details when this option is selected for payment.
This is usually fairly generic between the credit card modules, but you will need to ensure that your naming of your files remain the same as well.

function selection: Purpose is to provide a set of form information when the payment module is selected. The form information is used to render the form required fields, such as Credit Card number etc. The javascript validation provided in the above javascript_validation method will work off the field names setup here. If you are using a bank hosted integration model, or one that does not require user input of credit card you can return only the id and module. Check another payment module for the syntax.
function pre_confirmation_check: Purpose is to validate the details that have been submitted for the form that we created above. This needs to be very thorough. If you are using this payment method for the validation of a Credit Card you may like to make use of the validation class cc_validation.php bundled with osCommerce. Other payment modules will help you which its use. If the form fields don’t validate, this function will redirect the user back to the payment selection screen.

Second Stage, Confirming the order

function confirm: Purpose is to confirm to the user the details that will be used to process the order. Once again this is in an array format that defines keys that will be read in on the confirmation page.

function process_button: This allows us to place in hidden form fields into the confirmation page. These are provided to you by your payment gateway. You will need to carefully analyse which fields need to be placed here - as they are parsed through the request (only) to the next process:

Third Stage, Processing the payment

function before_process: This is where all of our actions go for processing the payment (prior to the order being saved). If you are using a Bank Hosted model this is called after the user has been to the bank and is returning. You will need to validate the request (eg, $_GET/$_POST) to ensure that the bank responded with the correct details. If you are submitting to the bank directly using CURL or similar, you will perform you actions here also to determine if the order should be continued to be processed, or to divert the user back to the payment details screen. This method doesn’t return a value, instead you will need to perform your validation and redirect if necessary. Otherwise allow the function to terminate and it will continue to process the order.

function after_process: This is called after the order has been saved. I don’t usually have a need for this method.

Misc Methods required for the payment module to integrate into osCommerce

function get_error: Create an associative array to house the error. Check syntax from existing payment module

function check: Checks whether the payment has been “installed” through the admin panel. You can determine this by checking for configuration_values which get inserted into the database when the user hits “install”.

function install: Installs the configuration keys into the database. This is where you define the fields to be collected from the adminsitrator user, such as Merchant ID’s etc.

function remove: Removes the configuration keys from the database, called when they hit “remove” in the backend.

function keys: Defines an array containing the configuration key keys that are used by the payment module.

For an example for one that I contributed to osCommerce for MIGS - ANZ, Bendigo use etc checkout the link to the payment module: MIGS Payment Module

I recommend for people to indicate on their module: Proper PHPDoc tags for functions, break up the method access into accessor style methods, try to leave a much notes for future developers (even yourself) such as “//” sections that indicate what you are doing etc. Also ensure to TODO notes where you have not completed a section of the integration, and also quote any documentation versions that you have used.

Lastly to complete the Payment Module you should include correct documentation that outlines how to install via FTP etc.