Dimuthu's Blog » mtom

Sending Encrypted Binary Messages With PHP Web Services

dimuthu — Sun, 14 Dec 2008 17:51:04 +0000

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 = <<"http://wso2.org/wsfphp/samples/mtom">
               test.jpg
               "image/jpeg" xmlns:xmlmime="http://www.w3.org/2004/06/xmlmime">
                  Include xmlns:xop="http://www.w3.org/2004/08/xop/include" href="cid:myid1">
               

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.

WSF/PHP Test Cases Explained

dimuthu — Tue, 11 Nov 2008 19:27:10 +0000

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.

WSF/PHP Samples Explained

dimuthu — Fri, 07 Nov 2008 12:20:02 +0000

Here is a simple categorization of the WSF/PHP samples. You can access all the wsf/php samples from http://labs.wso2.org/wsf/php/solutions/samples/index.html.

Sample Category	Example Client Source Code	Example Service Source Code	Online Demo
Beginners	echo_client.php	echo_service.php	Demo
REST	echo_client_rest.php	echo_service_with_rest.php	Demo
WSDL Mode (Contract First)	wsdl_11_client.php	wsdl_11_service.php	Demo
WSDL Generation (Code First)	doclit_client.php	doclit_service.php	Demo
MTOM Attachments	mtom_download_client.php	mtom_download_service.php	Demo
Security	encryption_client.php	encryption_service.php	Demo
Reliable Messaging	echo_client_rm.php	echo_service_rm.php	Demo
Data Services	CustomerDetailsClient.php	CustomerDetailsService.php	Demo

If you have downloaded the WSF/PHP binaries or souce code package you can find all these samples, inside the ‘samples’ directory

Send Binary With Web Services in PHP – 2 Minutes Introduction

dimuthu — Mon, 22 Sep 2008 17:14:53 +0000

In PHP you have several ways of sending binary data. It can be primarily categorized in to non-optimized method (send as base64 binary) and optimized method (send as MTOM or SWA). Here I m talking about how to send binaries in above mentioned methods starting from a WSDL.

WSDL

Think you have a WSDL with the following XML Schema.