Mtom | Dimuthu's Blog

Web services has made the communication between heterogeneous environments (say PHP with .NET or Java) a reality. It has defines standards for communicate not only with texts but also with binaries. And more importantly you can keep these communication confidential using encrypted messages according to your requirement. In this post, we will look at how we can implement such a system with PHP in one side.

In web services we can send/receive binary messages in two basic forms.

Setting the binary inside the SOAP message. - Binary should be converted to base64 to make sure the SOAP body contains only texts. Since base64 converted data span longer than the binary data, we call this form as non-optimized way of sending binaries.
Setting the binary outside the SOAP message - Binary would be sent as a MIME part in the message. And some element inside SOAP body keeps a reference to the binary using the MIME id. MTOM is a standard for referencing the MIME from inside the SOAP body. Since the binary is encoded, this will keep the message optimum with the binaries.

In WSF/PHP you can use any of these methods as you prefer. Lets forget about the encryption for now. We will check how we can send binaries in both of the above mentioned forms.

// first the request xml. Note tht xop:Include element that is referring the attachment with the id "myid1".
$reqPayloadString = <<<XML
<ns1:upload xmlns:ns1="http://wso2.org/wsfphp/samples/mtom">
               <ns1:fileName>test.jpg</ns1:fileName>
               <ns1:image xmlmime:contentType="image/jpeg" xmlns:xmlmime="http://www.w3.org/2004/06/xmlmime">
                  <xop:Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:myid1"></xop:Include>
               </ns1:image>
</ns1:upload>
XML;

try {
    $f = file_get_contents("my_binary_file.jpg");

    // here in the attachments option we define the binaries
    // corresponding to the id defined in the above XML
    $reqMessage = new WSMessage($reqPayloadString,
                                array("to" => "http://localhost/simple_upload_service.php",
                                      "action" => "http://wso2.org/upload",
                                      "attachments" => array("myid1" => $f)));

    // creating the WSClient
    // here the option useMTOM will decide whether the
    // attachment is set MTOM or base64
    $client = new WSClient(array("useWSA" => TRUE,
                                 "useMTOM" => TRUE));

    // sending the message and retrieving the response
    $resMessage = $client->request($reqMessage);

    printf("Response = %s \\n", $resMessage->str);

} catch (Exception $e) {

    if ($e instanceof WSFault) {
        printf("Soap Fault: %s\\n", $e->Reason);
    } else {
        printf("Message = %s\\n",$e->getMessage());
    }
}

As mentioned in the inline comment we can choose the preferred form of sending binary using the “useMTOM” option. if it is true, the binary is set as a MTOM, (referencing from the body) or if it is set false, the binary will be set as a base64 binary within the SOAP body.
To encrypt the message you only need to write few additional lines. First you define your policy that you need to encrypt this message using a WSPolicy object. Then the security token including the service public key and your private key. You need to give these two option as a constructor argument in WSClient. Here is that little additional code you need to write to add the encryption.

    // loading the keys
    $rec_cert = ws_get_cert_from_file("receiving_server.cert");
    $pvt_key = ws_get_key_from_file("my_private_key.pem");

    // here we defines the policies and create WSPolicy object
    $sec_array = array("encrypt" => TRUE,
                       "algorithmSuite" => "Basic256Rsa15",
                       "securityTokenReference" => "IssuerSerial");

    $policy = new WSPolicy(array("security" => $sec_array));

    // defining Security Tokens
    $sec_token = new WSSecurityToken(array("privateKey" => $pvt_key,
                                           "receiverCertificate" => $rec_cert));

    // modifing WSClient with adding WSPolicy and WSSecurityToken object
    $client = new WSClient(array("useWSA" => TRUE,
                                 "useMTOM" => TRUE,
                                 "policy" => $policy,
                                 "securityToken" => $sec_token));

You can implement the receiving side of the message similar to the sending side that we just described above. The most important thing is it doesn’t need to be written in PHP. It can be a Java code or .NET code.If you already have web services that use encrypted binary messaging, the above php code can be use out of the box to communicate with it.

WSO2 WSF/PHP comes with a comprehensive set of test cases. It covers the most of the basic/concrete scenarios supported by WSF/PHP. You can find these test cases inside the “src/tests” directory of WSF/PHP source package. Or you can find the latest test-suite from the SVN location.

Here are some aspects covered in the test-suit.

Scenario	Test Cases For Client	Test Cases For Service
Basic Functionality	echo_client.phpt math_.phpt	samples/echo_service*.php samples/math_service.php
Basic Schema Types	BasicDataTypes/*.phpt	services/BasicTypesDoclitBSvc/*.php
Complex Schema Types	cmplxDataTypes/*.phpt	services/ComplexDataTypesWSvc/.php services/ComplexDataTypesBSvc/.php
WSDL/Schema Variations	wsdl_mode/*.phpt	services/wsdl_mode/*.php
WSDL Generation with Annotations	wsdl_generation/*.phpt	services/wsdl_generation/*.php
Reliable Messaging	echo_rm*.phpt	samples/echo_service_rm*.php
Security	echo_encrypt_client.phpt echo_signing_client.phpt echo_timestamp_client.phpt echo_username_token_client.phpt	encrypt_service.php signing_service.php timestamp_service.php username_token_service.php
MTOM	mtom_*.phpt	samples/mtom/*.php

(Note that Here ‘*’ is used as a wild card represent 0 or many characters)

Steps to Run Tests

First you need to install WSF/PHP correctly. Please read the WSF/PHP installation manual for that.
You have to have the ‘pear’ utility tool comes with PHP. And add this to the PATH environment variable.
Copy the samples and src/tests/samples/services directory (paths are relative to the root directory of the wsf/php package) to the web root directory.
Then go to the src/tests directory and execute the following command.
```
pear run-tests -r
```
This will execute all the test cases under the ‘tests’ directory and finally give a summery of the test results.
You can run individual test cases separately by providing the relative path to the test case from the ‘test’ directory. E.g. To run the echo_client.phpt test case, you may type
```
pear run-tests samples/echo_client.phpt
```

If you like to add test cases for the WSF/PHP scenarios, follow this comprehensive guideline titled Writing Simple phpt Test Scripts For PHP Web Services.

Dimuthu’s Blog

December 14th, 2008Sending Encrypted Binary Messages With PHP Web Services

November 11th, 2008WSF/PHP Test Cases Explained