If you have been a developer for a while, chances are you’ll have come across the term DRY. It stands for Don’t Repeat Yourself, and it is actually a form of art. Keeping your code DRY ensures you have to think well before you start coding. Instead of randomly throwing code in your IDE, you should create the reflex of thinking how you can achieve what you want, without having to type too much code.

Not out of laziness, but because you’re smart. If you ever have to change your code, you’ll be glad you decided to write that particular bit only in that particular file. Sometimes it’s much easier to just copy/paste code from one class into another. But if you have to modify that piece of code, you’ll have to remember all the places that same code appears. Unless you kept it DRY of course.

Usually when an article talks about DRY, it will be in the context of Object Oriented Programming and model abstracts/inheritance/whatnot and making sure you don’t repeat the same code in different places. But the same principle can also be applied to other aspects of our code.

Other aspects that can be kept DRY

Use class constants

Not only does the DRY principle apply to OOP and methods in classes specificly. Other aspects of your classes should be kept DRY too. Recently, I’ve become a big fan of Class Constants in PHP. I use them to replace almost anything that is prone to change. I’ll just give you some examples:

Status checking

class MyClass {
    public function getStatus() {
        return "initialized";
    }
}
 
$object = new MyClass();
if ($object->getStatus() === "initialized") {
    // do some stuff
}

If it is decided that the status “initialized” should be renamed to “init”, then I have to change it everywhere I used that string literally.
Here’s how you could do it better:

class MyClass {
    const STATUS_INITIALIZED = "initialized";
 
    public function getStatus() {
        return self::STATUS_INITIALIZED;
    }
}
 
$object = new MyClass();
if ($object->getStatus() === MyClass::STATUS_INITIALIZED) {
    // do some stuff
}

If we now have to change “initialized” to “init”, then we only have to change the constant. All other code is left unchanged, and will still work. Now that is DRY.

Database metadata

In a database, the ENUM datatype is often used to restrict the content of a field to a specific set of data it can contain. Excellent examples are the status of the previous example, flags, … Basically, anything you want to have full control of what could be a possible entry in that field. Keep these values also in Class Constants. If you change the database, then the only other manual thing you have to do, is update the associated constant.

Configuration

Since I use the Zend Framework on a daily basis, here’s an example of how Zend Framework uses constants. First let’s see how it should not be done:

$translate = new Zend_Translate(
    'gettext',
    'my_it.mo',
    'auto',
    array('scan' => 'filename'));

Instead, they use constants:

$translate = new Zend_Translate(
    'gettext',
    'my_it.mo',
    'auto',
    array('scan' => Zend_Translate::LOCALE_FILENAME));

Keep your templates DRY

Not only is it important to keep your business logic DRY, the templates you write should benefit from the same principle. For your website basic, you won’t rewrite the entire HTML structure for each page on your site. Even if you don’t use PHP in an OOP way, you will probably still use includes to include parts on your site that will return on every page. Like the menu, or the header and footer. That’s DRY. But there’s more.

Use partials (in partials)

Partials is a term from Zend Framework. They are small templates that can be reused anywhere in your larger templates. Say you have a community site, with a messaging feature. Users can send each other messages, users can receive site notices, friend invitations, … In the inbox of a user, according to the type of message, a different partial can be shown:

foreach ($messagesList as $message) {
	$this->partial('/path/to/inbox_' . $message->__toString() . '.phtml',array('item' => $message));
}

For each messagetype that can be shown in the inbox, we create a new template. Inside that template, we do the markup for that specific message. Now in the inbox, we want to show the avatar and username of the person who sent you the message, or who invited you to become his friend. It is very tempting to write that part of the template once in inbox_message.phtml, and then copy/paste it in inbox_invitation.phtml and inbox_notice.phtml. It usually happens in a flurry of “yaaay it works !!”, and you’re so happy that you don’t care if your code becomes sloppy.

Of course, the avatar and username should be put in a new template. That new template is then used in each inbox_* template. Hence the partials inside partials. You also want to add the user ranking? No problem, only 1 file to update.

Conclusion

The DRY principle isn’t only reserved for the big chunks of your business logic. It is also an important part of the details. The small things that can easily lead to a search-and-replace rampage throughout your files. The templates are also often forgotten to be kept DRY.

As with many things: think before you act

So how do you set everything up properly?

First step: set include path

When you’re setting your include paths, just add one for DomPDF.

1

set_include_path(APPLICATION_PATH . "/../../library/dompdf-0.5.1" . PATH_SEPARATOR . get_include_path());

Second step:  make ZF & DomPDF play along

DomPDF has an autoloader which should take care of autoloading the classes for you. All you need to do, is make Zend Framework aware of that autoloader. The solution I found the most was this:

1
2

require_once 'dompdf_config.inc.php';
spl_autoload_register('DOMPDF_autoload');

However this may not work if you use Zend Framework 1.8 or newer. The real solution I found on a forum, where Matthew Weier O’Phinney enlightened another soul with the same problem:

1
2
3

require_once 'dompdf_config.inc.php';
$autoloader = Zend_Loader_Autoloader::getInstance(); // assuming we're in a controller
$autoloader->pushAutoloader('DOMPDF_autoload');

Final step: generate the PDF

That’s the simplest one, as I found no problems with that:

1
2
3
4
5
6

$dompdf = new DOMPDF();
$dompdf->set_paper("a4","portrait");
$dompdf->load_html($html);
$dompdf->set_base_path($_SERVER['DOCUMENT_ROOT']);
$dompdf->render();
$dompdf->stream("document.pdf");

There you go, this should set you up to get DomPDF up and running.

First things first: if you have read my previous posts about securing your Flex – PHP services, you will have seen that I have wrapped the bootstrapping process of that application in a class named “CB_Application”. That class is still under very heavy development. Since the release of Zend Framework 1.8, they have introduced Zend_Application, just for that purpose. So it is very likely that in the future, I will replace my CB_Application class with something that makes use of Zend_Application. For now, I will focus on the other functionality, and leave CB_Application as it is, without bothering you with the details. But full disclosure will come, somewhere in the future.

Structure

I haven’t decided on some kind of structure for this framework yet. I think it will evolve as I add more classes and functionality to it. Below is a screenshot of how it currently looks like.

Codebase Structure

As you can see, quite empty. What we will be constructing during this blog post, is the CB_User class, the CB_Table_Users class and the CB_Auth_Adapter_Chap class. Once that is complete, you should include the Code Base folder into your include paths in your bootstrap. If that is done, you can just simple use your framework anywhere in your models or controllers.

Database tables for the User class

I’m going to concentrate on the authentication of the users, so I will keep the amount of data small. It will be the base for the User class, and will be extended with functionality and other data as the framework evolves. Right now, the only properties for a user we need, are: a username, a password, an e-mail address, and a flag to indicate if the user is active or not.

1
2
3
4
5
6
7
8

CREATE TABLE IF NOT EXISTS `cb_users` (
  `id` int(5) NOT NULL AUTO_INCREMENT,
  `username` varchar(30) NOT NULL,
  `password` varchar(255) NOT NULL,
  `email` varchar(255) NOT NULL,
  `active` tinyint(1) NOT NULL DEFAULT '1',
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8;

Small remark:All passwords are encrypted via the AES encryption method. I won’t use a hashing algorithm, because during the authentication process, I would like to know the exact password. In case I want to build PHP services for Flex, I will need that password, and I can’t come from the client directly. But that’s nothing to worry about now; just remember that the password will be encrypted via AES.

For testing purposes, we will add a dummy user via SQL now. Normally this will be done during some sort of registration process, but that’s for the future. Let’s add the user “test” with password “password” into the database. As key for the AES encryption, I have used “c0d3ba53″. You know, l33t speak as they say You should remember that key. I will hard code it into the code, as this is just a demonstration. In my real code, I have this key in a configuration file, and it is fetched by CB_Application. (I know, it’s irritating, but it will come up here an there during this blog post. Sorry!)

1

INSERT INTO cb_users (username,password,email,active) VALUES ('test','S		í‹ôÚ×ýfÕ‘ˆ?	','test@example.com',1);

Building the authentication

Authenticating a user will be very straightforward. There is only 1 condition: I want to be able to use CHAP and regular authentication. CHAP requires 3 parameters (username, challenge, signature) and regular authentication requires only 2 (username, password). I will incorporate that into 1 authentication function that will dynamically decide which authentication we will be doing, via the amount of parameters.

As I said before, the authentication process will make use of the Zend_Auth component of the Zend Framework. There are many different ways you could authenticate a user. Most commonly is against a database. Zend_Auth can accommodate to all these different ways, by making use of adapters. An auth adapter basically does the authentication, and Zend_Auth uses it. There are already some predefined adapters, but for the CHAP authentication, we will have to create our own.

To access all the data from the cb_users table in the database, We extend the regular Zend_Db_Table class with our own information:

1
2
3
4

class CB_Table_Users extends Zend_Db_Table_Abstract {
	protected $_name = 'cb_users';
	protected $_primary = "id";
}

Nothing fancy, we just specify our table name, and the primary key, and then we’re good to go.

Before we can do the authentication, we first need to create our custom CHAP authentication adapter. The Zend Framework is designed to be extensible, and there is in interface for creating your own authentication adapters. The only method you need to implement is the authenticate() method. But you can add other methods if you deem that necessary. I will implement some setters for the credentials, and then a method that mimics the behaviour of the getResultRowObject() method from Zend_Auth_Adapter_DbTable. I added this extra functionality, because that will make it easier to process everything in the CB_User class. I have overdone myself documenting all the code, so I won’t explain it in depth anymore. If you are considering using this code, please replace all references to CB_application with your own code.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

/**
 * CB_Auth_Adapter_Chap class
 *
 * @author Tom Van Herreweghe
 */
 
class CB_Auth_Adapter_Chap implements Zend_Auth_Adapter_Interface {
    private $_username = '';
    private $_signature = '';
    private $_challenge = '';
 
    private $_data = null;
 
    /**
     * Set the username
     *
     * @param string $username
     */
    public function setUsername($username){
        $this->_username = $username;
        return $this;
    }
 
    /**
     * Set the challenge, used to calculate the signature
     *
     * @param string $challenge
     */
    public function setChallenge($challenge){
        $this->_challenge = $challenge;
        return $this;
    }
 
    /**
     * Set the client-side calculated signature
     *
     * @param string $signature
     */
    public function setSignature($signature){
        $this->_signature = $signature;
        return $this;
    }
 
    /**
     * Authenticate the user
     *
     * @return Zend_Auth_Result
     */
    public function authenticate(){
        // First, we need to retrieve the data, associated with the given username.
        // The password will be decrypted for later use:
        $table = new CB_Table_Users();
        $select = $table->select()->from(CB_application::getInstance()->getTablePrefix("cb") . "users",array("id","username","email",CB_application::getInstance()->getDbAdapter()->quoteInto("AES_DECRYPT(password,?) AS password",CB_application::getInstance()->getKey())));
        $select->where("username = ?",$this->_username)->where("active = 1");
        $result = $table->fetchAll($select);
 
        $authenticated = false;
        // If we found a match, verify the other credentials
        if (count($result) == 1){
            $password = $result[0]->password;
            $this->_data = $result[0]->toArray(); // store the database data locally
 
            // Compare calculated signature with given signature:
            $calcSignature = md5(md5($password) . $this->_challenge);
 
            // if the given signature and the calculated signature match, the user is authenticated:
            $authenticated = ($calcSignature == $this->_signature);
        }
        // We prefill the authentication result with a FAILURE
        $authResult = Zend_Auth_Result::FAILURE_UNCATEGORIZED;
        $authMessages = array();
        if ($authenticated){
            // user is authenticated, overwrite the auth result:
            $authResult = Zend_Auth_Result::SUCCESS;
        } else {
            // Couldn't authenticate the user, set a message:
            $authMessages[] = 'Login failed';
        }
        // return the result:
        return new Zend_Auth_Result( $authResult, $this->_username, $authMessages );
    }
 
    /**
     * Mimics (actually almost copies) the behaviour of the getResultRowObjec() from Zend_Auth_Adapter_DbTable
     *
     * @param array $returnColumns
     * @param array $omitColumns
     * @return stdClass
     */
    public function getResultRowObject($returnColumns = null, $omitColumns = null){
        // If no data is set, return false:
        if (!$this->_data) {
            return false;
        }
 
        $returnObject = new stdClass();
 
        if (null !== $returnColumns) {
            // Process only the specified columns:
 
            $availableColumns = array_keys($this->_data);
            foreach ( (array) $returnColumns as $returnColumn) {
                if (in_array($returnColumn, $availableColumns)) {
                    $returnObject->{$returnColumn} = $this->_data[$returnColumn];
                }
            }
            return $returnObject;
 
        } elseif (null !== $omitColumns) {
            // Process all columns, except the ones specified:
 
            $omitColumns = (array) $omitColumns;
            foreach ($this->_data as $resultColumn => $resultValue) {
                if (!in_array($resultColumn, $omitColumns)) {
                    $returnObject->{$resultColumn} = $resultValue;
                }
            }
            return $returnObject;
 
        } else {
            // Process all columns, without restrictions:
 
            foreach ($this->_data as $resultColumn => $resultValue) {
                $returnObject->{$resultColumn} = $resultValue;
            }
            return $returnObject;
        }
    }
}

The puzzle is almost complete now. Let’s put the pieces together in the CB_User class:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

/**
 * CB_User class
 *
 * @author Tom Van Herreweghe
 */
 
class CB_User {
    private $data = array();
 
    /**
     * Getter magical function to get properties
     *
     * @param string $key
     * @return mixed
     */
    public function __get($key){
        if (array_key_exists($key,$this->data)){
            return $this->data[$key];
        }
        throw new Exception("Unknown property '{$key}'");
    }
 
    /**
     * Setter magical function to set properties
     *
     * @param string $key
     * @param mixed $value
     */
    public function __set($key,$value){
        $allowed = array("id","username","email");
        if (in_array($key,$allowed)){
            $this->data[$key] = $value;
        }
    }
 
    /**
     * Authenticate a user via credentials
     * The amount of parameters is variable, and are therefore not explicitly declared
     *
     * @return Zend_Auth_Result
     */
    public static function authenticate(){
        // Get all the arguments:
        $args = func_get_args();
        // Initialize an authAdapter, but set it to null
        $authAdapter = null;
 
        if (count($args) == 2){
            // 2 arguments: We assume they are username & password. This means regular authentication
            $authAdapter = new Zend_Auth_Adapter_DbTable(
                CB_application::getInstance()->getDbAdapter(), // This returns an instance of a database adapter
                CB_application::getInstance()->getTablePrefix("cb").'users', // this will return a prefix, defined in a config.
                'username',
                'password'
            );
            // set the necessary credentials
            $authAdapter
                ->setIdentity($args[0])
                ->setCredential($args[1])
                ->setCredentialTreatment("AES_ENCRYPT(?, '".CB_application::getInstance()->getKey()."') AND active = 1");
                // CredentialTreatment says we'll use AES_Encrypt to encrypt the given password, and the user must be active.
                // CB_application::getInstance()->getKey() returns a predefined key from a config file.
        }
        if (count($args) == 3){
            // 3 arguments: We assume username, challenge and signature. This means custom digest authentication
 
            // Here, we use our custom created CB_Auth_Adapter_DbTable:
            $authAdapter = new CB_Auth_Adapter_Chap(
                    CB_application::getInstance()->getDbAdapter(),
                    CB_application::getInstance()->getTablePrefix("cb").'users',
                    'username',
                    'password'
            );
            // set the necessary credentials:
            $authAdapter
                ->setUsername($args[0])
                ->setChallenge($args[1])
                ->setSignature($args[2]);
        }
 
        if (is_null($authAdapter)){
            throw new Exception("No authAdapter specified. Please check all the arguments");
        }
 
        // Zend_Auth will now try to authenticate, using our auth adapter:
        $result = Zend_Auth::getInstance()->authenticate($authAdapter);
 
        if($result->isValid()) {
            /*
             * When authentication is succesfull, we will write an instance of CB_User to the storage
             * Later on, when we want to know which user is authenticated, we will retrieve this CB_User from the storage
             * This all hapens quite transparently via regular Zend Framework code
             */
 
            // get the resulting line from the database, except the "password" column:
            $data = $authAdapter->getResultRowObject(null,'password');
            // retrieve an an instance of CB_User via the user id:
            $user = self::getInstance($data->id);
            // write our CB_User object to the storage of Zend_Auth
            // Zend_Auth::getInstance()->getIdentity() will return that CB_User object
            Zend_Auth::getInstance()->getStorage()->write($user);
        }
        // Return the Zend_Auth result:
        return $result;
    }
 
    /**
     * Return an instance of the CB_User class, via the user_id
     *
     * @param int $user_id
     * @return CB_User
     */
    public static function getInstance($user_id){
        $table = new CB_Table_Users();
        $select = $table->select()->from(CB_application::getInstance()->getTablePrefix("cb") . "users",array("id","username","email"));
        $select->where("id = ?",$user_id)->where("active = 1");
        $result = $table->fetchRow($select);
 
        if (!is_null($result)){
            return self::factory($result);
        }
        throw new Exception("No user found");
    }
 
    /**
     * Transform the raw data from the database into a CB_User object
     *
     * @param Zend_Db_Table_Row $data
     * @return CB_User
     */
    public static function factory($data){
        if (is_a($data,"Zend_Db_Table_Row")){
            $user = new CB_User();
            $user->id       = $data->id;
            $user->username = $data->username;
            $user->email    = $data->email;
            return $user;
        }
        throw new Exception("Wrong datatype for the CB_User::factory() method");
    }
}

Now that we have written our classes, we want to use them. Mind you, this is just a demonstration. We will first log the user in via the CHAP method, then we do a logout, and then we log the user in via the regular method.:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

class IndexController extends Zend_Controller_Action{
    public function indexAction() {
        $this->getHelper("Layout")->disableLayout();
        $this->getHelper("ViewRenderer")->setNoRender();
 
        // Verify if we aren't logged in yet
        if (Zend_Auth::getInstance()->hasIdentity()){
            // Oops, we were still logged in from a previous demonstration..
            // Let's log out:
            Zend_Auth::getInstance()->clearIdentity();
        }
        // Alright, at this point we're not logged in.. Let's proceed:
 
        $challenge = 'challenge'; // <- this should be a random string
        $password = 'password';
        // Calculate the signature:
        $signature = md5(md5($password) . $challenge);
        // Authenticate via CHAP:
        $result = CB_User::authenticate('test',$challenge,$signature);
        // Show the result
        print_r(Zend_Auth::getInstance()->getIdentity());
 
        // Logout again for another demonstration:
        Zend_Auth::getInstance()->clearIdentity();
        // Lets try the other authentication method:
        $result = CB_User::authenticate('test',$password);
        print_r(Zend_Auth::getInstance()->getIdentity());
        die("demonstration is over !");
        }
}

That’s it for now. We have completed a first part of a framework: create a User class, and allow a user to authenticate. Right now, we can’t do much with it yet, but it will come in handy. We still need a way of registering users, but most importantly, we have to determine what that user can do now that he’s logged in. I will write about that in another blog post about Zend_ACL.

Project structure

For the project, I used a slightly modified Conventional Modular layout. The basics remains the same, but I have added support for so called versions of the application. The layout I maintain is not really important for the project. However, at the end of the article, you’ll be able to download everything, and I thought it necessary to explain the structure first. All code is part of the default module, and all classes are located in the “models” directory.

Application layout

The remoting endpoint

Flex and AIR need to connect to an endpoint. A URL you provide, the point of access to your API. I have created only 1 endpoint. Ideally, you should make 2 endpoints: one for logging in, and one for the rest of the calls. That way, in the future, you could do the login process via an SSL secured line. The remoting endpoint is located in the IndexController.php, since that file is the door to the outside world for the project.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

	// Explicitly loading dependencies
	Zend_Loader::loadClass("Proxies_AMF_System");
	Zend_Loader::loadClass("Proxies_AMF_Login");
	Zend_Loader::loadClass("AMF_VO_Error");
	Zend_Loader::loadClass("AMF_VO_Message");
 
	class IndexController extends Zend_Controller_Action{
		/**
		 * Everything to handle the rest of the API requests
		 */
		public function indexAction() {
			$this->getHelper("Layout")->disableLayout();
			$this->getHelper("ViewRenderer")->setNoRender();
 
			$server = new Zend_Amf_Server();
			$server->addDirectory(dirname(__FILE__) . "../models/");
			$server->setClassMap("MessageVO","AMF_VO_Message");
			$server->setClassMap("ErrorVO","AMF_VO_Error");
			$server->setProduction(false);
			$response = $server->handle();
			echo $response;
		}
	}

Basically, the indexAction is where my endpoints is. There I set up the Zend_AMF server. After setting it up, the server is ready to listen to requests. All requests are handled by the classes from the folder specified with addDirectory(). In our case, the Proxy classes will handle all the requests. After specifying the directory of the classes, we set up the class mapping. Here, we tell Zend_AMF, how the mapping should be between our PHP classes on the server side, and the Flex classes on the client side. In my case, all Flex classes end with “VO”. Once the mapping is complete, our server is ready to give a response to the client. Note that I explicitly load every class in IndexController.php. For some reason, Zend_AMF isn’t able to use autoloading, which is a too bad.

Responses to the client

To have a cleaner interface, I have opted to return structured responses to the Flex client. When the client makes a call, there are only 2 kind of responses he can expect. When the call is successful, the response will be an object of the type AMF_VO_Message that’s being mapped to a MessageVO in Flex. Or it will be an object of the type AMF_VO_Error, mapped to ErrorVO, when an exception is thrown. This is very easy for the client side coder. All other data is encapsulated in the AMF_VO_Message object, and that makes it easy to process everything. It’s also easier for the PHP developer, since it is now possible to return a lot more information to the client. If you decide to use caching, then the AMF_VO_Message response can contain information about that; timestamps; transaction id’s; … Anything you would expect an API to return.

1
2
3
4
5
6
7
8
9
10
11
12

    /**
     * This class is used to wrap data for output to the AMF adapter
     *
     */
    class AMF_VO_Message {
        // Properties:
        public $status		= null; // string
        public $timestamp	= null; // string
	public $transaction	= null; // string
	public $data		= null; // mixed
	public $cachehit	= false; // boolean
    }

The class is basically a collection of public properties, where I can add data that is useful for the client, like timestamps, transaction-id’s, …

1
2
3
4
5
6
7
8
9
10
11
12

    /**
     * This class is used to wrap data for output to the AMF adapter
     *
     */
    class AMF_VO_Error {
        // Properties:
        public $timestamp	= null; // string
        public $errorCode	= null; // string
        public $file		= null; // string
        public $linenumber	= null; // integer
        public $messages	= null; // string
    }

Again, some properties that are useful for error tracking.

First phase: login security

In the first part of this series, I explained how securing the login process works. To initialize a login procedure, the client first needs to notify the server that an authentication attempt will be made. This is done by means of the challenge() function from the Proxies_AMF_Login class. Remember, all available calls are exposed via my so called Proxy classes. This is not mandatory, but a convention I want to impose on the users of the API I’m going to write. In Flex, the front-end developer can specify the class (proxy) and method (API call) to invoke.

When a client request a challenge from the server, I don’t necessarily want to know. Therefore, I can keep this function clean and simple. All code is explained with in-line comments.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

/**
 * Login proxy class to expose classes to AMF
 *
 */
class Proxies_AMF_Login extends Proxies_AMF {
        /**
         * Start the authentication session, by requesting a challenge.
         * The client then uses this challenge to calculate a signature (or digest)
         * When signing on, the username & signature is used, instead of the password
         *
         * @return AMF_VO_Message
         */
        public function challenge(){
		$arguments = func_get_args();
		return $this->processRequest(__FUNCTION__,$arguments);
	}
 
        protected function _challenge(){
            // 1. generate the challenge
            $challengeString = AMF_Login::generateChallenge();
            // 2. remember the challenge !
            $amfNamespace = new Zend_Session_Namespace('AMF_Auth');
            $amfNamespace->challenge = $challengeString;
            // 3. return the challenge to the client
            return $challengeString;
	}
 
        /**
         * Authenticate the user
         *
         * @param string $username
         * @param string $signature
         * @return bool|AMF_VO_Error
         */
        public function signOn($username,$signature){
			$arguments = func_get_args();
			return $this->processRequest(__FUNCTION__,$arguments);
	}
 
	protected function _signOn($username,$signature){
            // 1. Digg up the challenge from our memory:
            $amfNamespace = new Zend_Session_Namespace('AMF_Auth');
            $challenge = $amfNamespace->challenge;
 
            // 2. Verify if we can authenticate the user
            if (AMF_Login::signOn($username,$challenge,$signature)){
            	// User authenticated, let's forget the challenge
                unset($amfNamespace->challenge);
                return true;
            } else {
            	// Failed to authenticate the user
            	unset($amfNamespace->challenge);
		Zend_Auth::getInstance()->clearIdentity();
                throw new Exception("Could not authenticate the user");
            }
	}
}

A challenge() call is logically followed by a signOn() request (verifySignature() will be explained later on) to complete the login process. As you can see, for both challenge() and signOn(), there is a protected counterpart _challenge() and _signOn(). This has to do with the processRequest() call in both of the methods. More about that call later on, but for now, you only need to know that processRequest() does some administrative tasks, and wraps the responses for Zend_AMF server in a structured response.

An attentive reader will have noticed that I make use of an AMF_Login class, and I forgot to explain what and how. No wories, it’s not very mystical. I have just created that class to bundle some functionality. However, it does use some functionality from classes I have not written myself. They fall under the copyright of my employer, and I don’t want to infringe on that. So I won’t show you how AMF_User is written, but from the comments, it should be obvious what the purpose is. In the downloadable source, you’ll find a simplified version of AMF_User, which doesn’t really do anything, except illustrating the purpose.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

class AMF_Login {
	/**
	 * Returns a random string, that is used as Challenge for the sign-on
	 * procedure
	 *
	 * @return string
	 */
	public static function generateChallenge(){
		return uniqid(rand()+time(),true);
	}
 
	public static function signOn($username,$challenge,$signature){
		$user = new AMF_User();
		$result = $user->authenticate($username, $challenge, $signature);
 
		return $result;
	}
 
	/**
	 * Method to verify if each signature for an API call is valid
	 */
	public static function verifySignature($challenge,$signature){
		// 1. get the password from the session (it was put there during authentication)
		$amfNamespace = new Zend_Session_Namespace('AMF_Auth');
 
		// 2. calculate signature with given $challenge
		$calcSignature = md5(md5($amfNamespace->password) . $challenge);
 
		// 3. compare calculated signature, with given signature
		if ($calcSignature == $signature){
			return true;
		}
		throw new Exception("Incorrect signature given");
		return false;
	}
}

This concludes the first part of the security measures: logging in. By now, a user can be logged in, and stay logged in, by means of the browser session.

Second phase: API call security

In the second phase, I want to verify all API calls. What we need, is a way to process every API call, and do a number of actions for each of those call. I want to be able to:

• Log what calls were made, by what user, what arguments, and what was the response
• Have the possibility to cache certain calls
• Use Zend_ACL to verify if a certain user has access to certain functionality
• Create my structured response
• Trap errors (yes, they should be trapped in the ErrorController.php, but I haven’t fully investigated that option yet)
• Write code once, use it multiple times

As you can see, there are plenty of requirements. There is one option to fulfil them all: Make sure all calls invoke 1 function that handles all the “administration”. The perfect solution exists, and is named __call() in PHP5. If a method does not exist in a class, then the __call() magic function is called with the exact same arguments. There, you can create all functionality for the administration, and then request another function that will do the real work. I know, quite the abstract explanation, but I won’t go any further on that road because using __call() fails. Zend_AMF uses Zend_Reflection, a PHP reflection class. Simply put, a reflection calls detects all publicly accessible methods and properties of a given class. Since __call() is a magic function, it isn’t publicly accessible. Hence, it won’t be discovered by Zend_Reflection, and consequently, Zend_AMF will not be able to make use of your functionality if you rely on __call(). That took me a while to discover, but if you think about it, it’s quite logical.

To work around this problem, I have decided to create my own __call() method, and I have named it processRequest(). This will do the exact same as I have explained in the paragraph above: handle the administration (logging, caching, …). The diagram below will immediately shine a light on the working.

Diagram: handle requests

A request comes in via helloWorld(). It then travels to processRequest() for the administrative tasks. Next it travels to _helloWorld() that will do what needs to be done and give a response. The response then will travel back from _helloWorld() to processRequest(). There, the response is packed in the structured response, and then that structured response is sent back to helloWorld(). There, it is delivered to the Zend_AMF server, and ultimately, to the Flex client.

To write the code only once and use it many times, the only option is to place the processRequest() function in the parent of our Proxy classes: Proxies_AMF.php. Below, you will find a simplified version of the code I have written for a recent project. Everything is explained in in-line comments.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

/**
 * AMF proxy class to expose classes to AMF
 *
 */
class Proxies_AMF {
	// Some classes do not need verification, like Login. Only the other API calls should be verified
	private $exemptVerification = array("Proxies_AMF_Login");
 
	protected function processRequest($method,$arrArguments){
		try {
			$className = get_class($this);
 
			// Retrieve the parameters to verify the identiy of the requesting party:
			if (!in_array($className,$this->exemptVerification)){
				$challenge = array_shift($arrArguments);
				$signature = array_shift($arrArguments);
			}
 
			// Verify the given signature, before executing the call, unless the request is to a method from an exempt class:
			if (in_array($className,$this->exemptVerification) || AMF_Login::verifySignature($challenge,$signature)){
				// Verify if the requested method actually exists:
				if (method_exists($this,"_{$method}")){
					$cachehit = false; // support for caching could be added, but not now.
					$returnValue = call_user_func_array(array($this,"_{$method}"),$arrArguments);
 
					// wrap the response of the API call in an AMF_VO_Message object, and return it:
					return $this->wrapOutput($returnValue,$signature,$cachehit);
				} else {
					throw new Exception("The method '{$method}' does not exist.");
				}
			} else {
				// An exception is already thrown in AMF::Login::verifySignature()
			}
		} catch (Exception $e){
			$errorVO = new AMF_VO_Error();
 
			// Get the currently logged in user
			if (Zend_Auth::getInstance()->hasIdentity()) {
				$user = Zend_Auth::getInstance()->getIdentity();
				$errorVO->user_id = $user->user_id;
			} else {
				$errorVO->user_id = 0;
			}
			$errorVO->timestamp		= strftime("%Y-%m-%d %H:%M:%S");
			$errorVO->errorCode		= get_class($e); // usually, this will be "Exception", unless we introduce custom Exceptions
			$errorVO->file			= $e->getFile();
			$errorVO->linenumber		= $e->getLine();
			$errorVO->messages		= array($e->getMessage());
			$errorVO->stacktrace		= debug_backtrace();
 
			// return response
			return $errorVO;
		}
	}
 
	private function wrapOutput($data,$transaction,$cachehit){
		$message				= new AMF_VO_Message();
		$message->status		= "success";
		$message->timestamp	= strftime("%Y-%m-%d %H:%M:%S");
		$message->transaction	= (!is_null($transaction))?$transaction:"no_transaction";
		$message->data		= $data;
		$message->cachehit		= $cachehit;
 
		return $message;
	}
}

The function processRequest() is now very basic. It only incorporates authentication of the requester, and catching errors. I will not implement the rest of the requirements during this article, since that would lead me outside the scope of this article. If you feel like implementing extra functionality for all your calls, then processRequest() is the method to elaborate on. For a business project, I have extended it with everything mentioned in my list earlier.

The hard part is over now. Most of the functionality has been written. Each API call will be accompanied by 2 extra parameters: a client-chosen challenge, and a calculated signature. The given challenge and signature are just the first two parameters of each of our service calls. These parameters will be verified in processRequest().

The actual verification is done by the verifySignature() method in AMF_Login class. To make it easy, below is a copy of that method again. The parameters are the challenge, chosen by the client, and the signature, calculated by the client. The method will then use that same challenge, and the password stored in a session object, and then calculate the accompanying signature. If both signatures match, then we have a winner! If they don’t match, then somebody is trying to tamper with the requests. It’s up to you how you deal with that. I just output an AMF_VO_Error object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

/**
 * Method to verify if each signature for an API call is valid
 */
public static function verifySignature($challenge,$signature){
	// 1. get the password from the session (it was put there during authentication)
	$amfNamespace = new Zend_Session_Namespace('AMF_Auth');
 
	// 2. calculate signature with given $challenge
	$calcSignature = md5(md5($amfNamespace->password) . $challenge);
 
	// 3. compare calculated signature, with given signature
	if ($calcSignature == $signature){
		return true;
	}
	throw new Exception("Incorrect signature given");
	return false;
}

With this last functionality explained, I think I have everything covered. Only thing left, is giving you an example on how our processRequest() method is used:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

/**
 * System proxy class to expose classes to AMF
 *
 */
class Proxies_AMF_System extends Proxies_AMF {
	/**
	 * Say hello to the world
	 *
	 * @return string
	 */
	public function helloWorld(){
		$args = func_get_args();
		return $this->processRequest(__FUNCTION__,$args);
	}
 
	protected function _helloWorld(){
		return "Hello World !!";
	}
}

I mentioned the helloWorld() function earlier, and here is the implementation. The Flex client calls the helloWorld() function (without the underscore !!), and gives as paremeters the challenge and signature. You’ll see that those parameters aren’t explicitly mentioned in the function definition, but that is no problem. In that function, processRequest() is called, which will do the verificiation and then call _helloWorld(). The response from _helloWorld() will then travel back, over processRequest(), via helloWorld(), to Zend_AMF, stopping at the Flex client.

Ammendments

This article is the fruit of a quite lengthy development process at the company I work at. During this period, I have made many mistakes regarding Zend_AMF, and learned from them. To illustrate that development is a continuous learning process, I will end with a “mistake” I just recently discovered:

When I first implemented these security measures, I used the URL to transport the challenge and signature for each API call. This way, could keep my interfaces clean, without having to take into account the challenge and signature. In Flex, I had the front-end developer create a dynamical endpoint for each call. Each endpoint connection only made one call, since in the URL, the challenge and signature were added. However, when an endpoint connection is established, it is standard procedure of AMF to ping the server once. As a result, each call generated a new ping request, effectively doubling the amount of calls. I don’t have to explain that this is quite a big overhead. To overcome this, I had to extend each API call to accept the challenge and signature as a parameter of that call. And the result of my mistake is that you can enjoy a “better” implementation than what I had 2 days ago.

What I want to say: This method is not fool proof, and I have no doubt that there are probably many ways of improving the security. If you happen to have suggestions, by all means, let me know. I’m happy to learn from you.

Download all files: zip | tar
Credits where credits are due: Thanks Vic Rau for the small UnitTest (yes, it is also in the downloadable archive)

I’m currently working together with my friend and colleague Vic on a client-server application that involves Flex on the front-side, and PHP (Zend Framework) on the back. Since I’m the PHP guy, I’m in charge of creating the API for his Flex application. For the moment, the project will only be accessed locally from the client’s network. But there is a possibility that in a later stage, it might open up to the general public. One of my main concerns was how we could make every API call as secure as possible. This without making it too complicated, or involve too many service calls that might slow everything down.

First login…

The first aspect of securing the application, is authentication of users. The application is accessible to multiple users, and those are grouped in various groups. Each group has different privileges. To identify every user, they are given usernames and passwords. My biggest concern with the login process, is that we didn’t have access to a secure connection via SSL. This means that every communication between the client and server software can be monitored by network sniffers. Flex uses the AMF protocol to communicate with Zend_AMF. Even though this is a binary stream, the specifications are open to everyone. So it is possible to intercept communications, and read everything out.

I wanted to make sure that during the login process, the password was not exposed to the outside world via the communications line. Because once the password and username are intercepted, then it would be easy to start making fake API calls to the server. The solution I had in mind, is called CHAP – Challenge-Handshake Authentication Protocol. Here’s a diagram about how this protocol works.

The main purpose of using CHAP, is to authenticate users, without having to transmit the password between the client and the server. To accomplish this, we have to replace the password with something else, but still allowing the server to recognize the correct user, and log him in. I call this password replacer the “signature”.

In the first phase of the diagram, the client requests a “challenge” from the server. A challenge is a key that will be used by both the client and the server, to create the signature. During the first phase, the client asks the server what key will be used to encrypt the password. It is important that both the client and the server use the exact same challenge.

During the second phase, an authentication request is being transmitted. Instead of using the username and password, we use the username and signature. The final signature is calculated like this:

$signature = MD5(MD5($password) . $challenge);

The client calculates this signature, and sends it to the server. The server then looks up the given username in the list of possible users. The corresponding password is then used by the server, to also calculate a signature, with the earlier given challenge. The outcome of that comparison is given during the third and last phase of the CHAP authentication.

This is not a very difficult protocol to implement, but according to me, it still provides a reasonable amount of security during the login process.

… and then the rest of the calls.

Now that a user is logged in, the most important stuff still has to happen: interactivity with the server by calling API methods. Once the user is authenticated, he remains authenticated by using the browser session. So now we have to keep in mind that other people might try to steal the session, and invoke undesired API calls. During each call, the server needs to be sure that it was still the same client making the call, and not some man-in-the-middle.

For this, I decided to elaborate on the CHAP protocol, used for authentication. How about we could keep the system, where the client signs its calls with a signature. For obvious reasons, it is not possible to recycle the signature from the login procedure. But I wanted to force the client to generate a new signature for each API request. There are still two variables to generate the signature: the password and the challenge.

It was not a practical option to ask the user’s password for each and every API call. Instead, once the user was authenticated, I had the Flex application remember the password in its memory. This way, it could be recycled to generate new signatures.

The only problem was the challenge. A first option was to have the client request a challenge from the server. But this would mean that for each regular API call, there would be an additional call for a challenge. That would double the amount of API calls. I was afraid that in the long run, this would generate too much calls for the server. That’s why I chose a second option: have the client generate the challenge and transmit it alongside the signature. The server would then use this challenge, and the password from the session, to calculate the signature. If they matched, then the call was permitted to be executed.

As far as I could see, this wouldn’t impose a bigger security risk. Of course, a man-in-the-middle could generate fake challenges. But he still wouldn’t be able to generate fake signatures. For that, he still needs the correct password. Once he has that, then well… all security checks fail. The responsibility of keeping the password secret lies entirely at the client now.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

	$items = array(
		array(
			"field"		=> "field1",
			"value"		=> "value1",
			"options"	=> array(
				"operator"	=> "=",
				"logic"		=> "OR"
			)
		),
		array(
			"field"		=> "field2",
			"value"		=> "value2",
			"options"	=> array(
				"operator"	=> "=",
				"logic"		=> "OR"
			)
		),
		array(
			"field"		=> "field3",
			"value"		=> "value3",
			"options"	=> array(
				"operator"	=> "=",
				"logic"		=> "OR"
			)
		),
		array(
			"field"		=> "field4",
			"value"		=> "value4",
			"options"	=> array(
				"operator"	=> "=",
				"logic"		=> "OR"
			)
		)
	);

It is a simple array. It could be an array of where-clauses you wish to define for your own search module (like this example), or it could just simply be test data for a unit test.

In my case, this data comes into a function, and in that function I want to strip some of the data. The “logic” index under “options” is deprecated, and I want to remove it. To make my code compact, I have decided to alter each filter on the fly, by using the by-reference operator.

1
2
3
4
5

	foreach($items as &$item){
		unset($item["options"]["logic"]);
	}
 
	print_r($items);

This results in the following altered version of my initial data:

Array
(
    [0] => Array
        (
            [field] => field1
            [value] => value1
            [options] => Array
                (
                    [operator] => =
                )
 
        )
 
    [1] => Array
        (
            [field] => field2
            [value] => value2
            [options] => Array
                (
                    [operator] => =
                )
 
        )
 
    [2] => Array
        (
            [field] => field3
            [value] => value3
            [options] => Array
                (
                    [operator] => =
                )
 
        )
 
    [3] => Array
        (
            [field] => field4
            [value] => value4
            [options] => Array
                (
                    [operator] => =
                )
 
        )
 
)

As you can see, I have successfully removed the “logic” index by using an ampersand in my foreach loop. This is potentially very useful functionality. It’s very easy to manipulate your data like this. No more fiddling around with indexes, or even create temporary arrays to house your data. Just edit it on the fly. There is however a (big) flaw, and I’ll illustrate it below.

In the previous loop, I have altered my array, and now I want to loop through it again, and just output each item in the array. Nothing more. But things go awry quite unexpectantly.

1
2
3
4
5
6

	$counter = 1;
	foreach($items as $item){
		echo "Item {$counter}: ";
		print_r($item);
		$counter++;
	}

The output of this loop is:

Item 1:
 
Array
(
    [field] => field1
    [value] => value1
    [options] => Array
        (
            [operator] => =
        )
 
)
 
Item 2:
 
Array
(
    [field] => field2
    [value] => value2
    [options] => Array
        (
            [operator] => =
        )
 
)
 
Item 3:
 
Array
(
    [field] => field3
    [value] => value3
    [options] => Array
        (
            [operator] => =
        )
 
)
 
Item 4:
 
Array
(
    [field] => field3
    [value] => value3
    [options] => Array
        (
            [operator] => =
        )
 
)

The last output isn’t what I expected it to be. As you can see, it is the same output as the previous item “3″.

I have encountered this problem in production code, and only by rigorously outputting all my data, I have discovered that this was my problem. I am not a PHP expert by far. So I don’t always know how things technically work. My guess is that after a foreach loop, with the by-reference operator, the garbage collector doesn’t do its job well. But I’m not sure this is the correct explanation. I have found a workaround though. After the first foreach, where you use the & symbol, you just unset that variable. Like this:

1
2
3
4

	foreach($items as &$item){
		unset($item["options"]["logic"]);
	}
	unset($item);

Now the output should be what you expect it to be. Just to be sure, here’s what I got:

// ...
Item 4:
 
Array
(
    [field] => field4
    [value] => value4
    [options] => Array
        (
            [operator] => =
        )
 
)

If anyone has an idea to whether or not this is a bug, please let me know. I have so far not filed a bug (yet), as I feel I need to do a bit more research first. It could be something by-design, and then I’m making quite a fool of myself. I guess that’s just part of the learning process