8. Security Manual

8.1. Writing a Secure Web Service Client

First create a suitable payload to be sent to the echo service.

my $request_payload = '
        <ns1:echoString xmlns="http://www.wsf.org/echo/echoString">
            <text>Hello RM!</text>
        </ns1:echoString>
';

Note that in order to run security clients or services, you should engage WS-Addressing

my $message = new WSO2::WSF::WSMessage( { 'payload' => $request_payload,
                                          'to' => 'http://localhost/samples/security_service/callback',
                                          'action' => 'http://perl.axis2.org/samples/echoString'
                                        } );

Then create a WSPolicy object with the security options to match your requirements.

For example, if you want to include TimeStamp and UsernameToken you can do as follows.

my $security_options = { 'useUsernameToken' => 'TRUE',
                         'includeTimeStamp' => 'TRUE' };

my $policy = new WSO2::WSF::WSPolicy( { 'security' => $security_options } );

Note: If you wish to use a policy file instead of an options array you can directly set a policy XML file.

open XML, "< policy.xml";
undef $/;
my $policy_xml = <XML>;

my $policy = new WSO2::WSF::WSPolicy($policy_xml);

Next create a SecurityToken object with appropriate security properties.

If you want to have the UsernameToken, then the user, password and passwordType (optional) options must be set. For TimeStamp, the ttl option must be set. Hence the SecurityToken object is created as

my $security_token = new WSO2::WSF::WSSecurityToken( { 'user' => 'frodo',
                                                       'password' => 'icannothasring',
                                                       'passwordType' => 'Digest',
                                                       'ttl' => 300
                                                     } );

Then create the client using the policy object and security token object.

my $client = new WSO2::WSF::WSClient( { 'useWSA' => 'TRUE',
                                        'policy' => $policy,
                                        'security_token' => $security_token
                                      } );
 

8.2. Encryption and Signing

For encryption and signing, content of keys and certificates files should be loaded into Perl scalar variables as strings. You can do this easily using the slurp mode in Perl.

8.2.1. Encryption on the Client Side

The Receivers certificate (certificate used by the server side) must be set using the "receiverCertificate" option and the private key of the client must be set using the "privateKey" option with a WSSecurityToken object instance.

First load the certificates:

open MYC, "../keys/alice_cert.cert";
undef $/;
my $mycert = <MYC>;

open MYK, "../keys/alice_key.pem";
undef $/;
my $mykey = <MYK>;

Then the Policy object and the SecurityToken object have to be created.When creating the Policy object, you can also specify the algorithm suite to be used.

my $sec_arr = { 'encrypt'                => 'TRUE',
                'algorithmSuite'         => 'Basic256Rsa15'
              };

my $policy = new WSO2::WSF::WSPolicy( { 'security' => $sec_arr } );

my $sec_token = new WSO2::WSF::WSSecurityToken( { 'privateKey'          => $pvt_key,
                                                  'receiverCertificate' => $rec_cert
                                                } );

8.2.2. Signing on the Client Side

For signing, the certificate and the key of the client and the certificate of the server must be set.

open MYC, "../keys/alice_cert.cert";
undef $/;
my $mycert = <MYC>;

open MYK, "../keys/alice_key.pem";
undef $/;
my $mykey = <MYK>;

open REC, "../keys/bob_cert.cert";
undef $/;
my $reccert = <REC>;

Then the Policy object and the SecurityToken object can be created:

my $sec_arr = { 'sign'                   => 'TRUE',
                'algorithmSuite'         => 'Basic256Rsa15',
                'securityTokenReference' => 'IssuerSerial'
              };

my $policy = new WSO2::WSF::WSPolicy( { 'security' => $sec_arr } );

my $sec_token = new WSO2::WSF::WSSecurityToken( { 'privateKey'          => $mykey,
                                                  'certificate'         => $mycert,
                                                  'receiverCertificate' => $reccert
                                                } );

8.3. Code Sample on Encryption