The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
XML-Compile-WSS-0.90
River stage one • 4 direct dependents • 5 total dependents
2 ++
/ XML::Compile::WSS

NAME

XML::Compile::WSS - OASIS Web Services Security

INHERITANCE

 XML::Compile::WSS is extended by
   XML::Compile::SOAP::WSS

SYNOPSIS

 my $schema = XML::Compile::Cache->new(...);
 my $wss    = XML::Compile::WSS->new(version => '1.1'
   , schema => $schema);
 
 use XML::Compile::WSS::Util qw/:wss11 :utp11/;
 my $secPlain = $wss->wsseBasicAuth($username, $password, UTP11_TEXT);

 my $nonce     = 'some random string' ;
 my $created   = time();   # now (=default), or any pre-formatted date
 my $secDigest = $wss->wsseBasicAuth($username, $password, UTP11_PDIGEST
    , nonce => $nonce, created => $now, wsu_Id => 'foo');

 my $expires   = $created + 5 * 60;  # or any pre-formatted date
 my $sec_Time  = $wss->wsseTimestamp($created, $expires, wsu_Id => 'biz');

DESCRIPTION

The Web Services Security working group of W3C develops a set of standards which add signatures and encryption to XML.

In its current status, this module supports processing (reading and writing) of the XML meta-data involved, however there is no support for in-file encryption or signature checking (yet).

The examples directory included in the distribution of the module contains examples how to use it. There even is an extended example how to produce these structures (writing), but that is quite difficult where the standard uses "any" elements everywhere.

METHODS

Constructors

XML::Compile::WSS->new(OPTIONS)
 -Option --Default
  schema   undef
  version  <required>
schema => XML::Compile::Cache

Add the WSS extension information to the provided schema. If not used, you have to call loadSchemas() before compiling readers and writers.

version => '1.1'|MODULE

Explicitly state which version WSS needs to be produced. You may use a version number. You may also use the MODULE name, which is a namespace constant, provided via ::Util. The only option is currently WSS11MODULE.

Attributes

$obj->schema()
$obj->version()

Returns the version number.

Simplifications

$obj->wsseBasicAuth(USERNAME, PASSWORD, [PWTYPE, OPTIONS])

Many SOAP applications require a username/password authentication, like HTTP's basic authentication. See examples/usertoken/manually.pl for an example how to construct this by hand for any possible requirement. This method, however, offers a simplification for the usual case. See also working examples in examples/usertoken/with_help.pl and examples/usertoken/with_help_digest.pl.

The optional PWTYPE parameter contains either the UTP11_PTEXT (default) or UTP11_PDIGEST constant. The PTEXT is the plain-text version of the PASSWORD.

If PTWTYPE IS UTP11_PDIGEST, the plain-text password will be encrypted with SHA1. The OPTIONS can be used to salt the digest with "nonce" and/or "created" information before the encryption.

 -Option --Default
  created  undef
  nonce    undef
  wsu_Id   undef
created => STRING|TIME

An extra "created" child element will be added. The specification allows a free-format STRING. If you pass a number, it will get converted into the standard iso dateTime format automatically.

  <wsse:UsernameToken>
     ...
     <wsu:Created>$created</wsu:Created>

There is no mechanism for adding a ValueType attribute to this element. The time string will be prepended to the password before the digest is computed.

nonce => STRING

This will cause an extra child to be added to the UsernameToken, namely

  <wsse:Nonce>$enc</wsse:Nonce>

where $enc is the base64-encoding of the STRING. The STRING will be prepended to the password (and to any "created" information) before the digest is computed.

wsu_Id => STRING

Adds a wsu:Id attribute to the created element.

example: how to use wsseBasicAuth

  my $call     = $wsdl->compileClient($operation);
  my $security = $wss->wsseBasicAuth($username, $password);

  my ($answer, $trace) = $call->
    ( wsse_Security => $security
    , %payload
    );

  use XML::Compiles::WSS::Util ':utp11';
  my $sec = $wss->wsseBasicAuth($user, $password, UTP11_PTEXT);

  my $sec = $wss->wsseBasicAuth($user, $password, UTP11_PDIGEST
     , created => time());
$obj->wsseTimestamp(CREATED, EXPIRES, OPTIONS)

CREATED and EXPIRES are timestamps: either some STRING (any format is allowed by the spec, so hard to check automatically) or a NUMERIC which is converted to ISO dateTime format for you.

This method does not support adding a "ValueType" attribute to any of the elements. See a working example in examples/usertoken/with_help_digest.pl.

 -Option--Default
  wsu_Id  undef
wsu_Id => LABEL

Adds a wsu:Id attribute to the UsernameToken, namely

   <wsse:UsernameToken wsu:Id="LABEL">

example: how to use wsseTimestamp

   my $created = time();
   my $expires = '2019-08-17T12:07:26Z';
   my $expires = $created + 300;  # alternative: + 5 minutes
   my $node = $wss->wsseTimestamp($created, $expires, wsu_Id => 'label');

produces

   <wsu:Timestamp wsu:Id="label">
     <wsu:Created>2012-08-17T12:02:26Z</wsu:Created>
     <wsu:Expires>2019-08-17T12:07:26Z</wsu:Expires>
   </wsu:Timestamp>

Internals

$obj->loadSchemas(SCHEMA)

SCHEMA must extend XML::Compile::Cache.

The SCHEMA settings will may changed a little. For one, the allow_undeclared flag will be set. Also, any_element will be set to 'ATTEMPT' and mixed_elements to 'STRUCTURAL'.

SEE ALSO

XML Security Generic Hybrid Ciphers

http://www.w3.org/TR/2011/CR-xmlsec-generic-hybrid-20110303/, 3 March 2011

XML Signature Properties

http://www.w3.org/TR/2011/CR-xmldsig-properties-20110303/, 3 March 2011

XML Signature Syntax and Processing Version 1.1

http://www.w3.org/TR/2011/CR-xmldsig-core1-20110303/, 3 March 2011

SOAP message security

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf, March 2004

XML Signature Syntax and Processing (Second Edition)

http://www.w3.org/TR/2008/REC-xmldsig-core-20080610/, 10 June 2008

RFC4050 Using the ECDSA for XML Digital Signatures

http://www.ietf.org/rfc/rfc4050.txt, april 2005

RFC4051 Additional XML Security Uniform Resource Identifiers (URIs)

http://www.ietf.org/rfc/rfc4051.txt, april 2005

XML Encryption Syntax and Processing

http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/, 10 December 2002

SEE ALSO

This module is part of XML-Compile-WSS distribution version 0.90, built on August 30, 2012. Website: http://perl.overmeer.net/xml-compile/

Other distributions in this suite: XML::Compile, XML::Compile::SOAP, XML::Compile::SOAP12, XML::Compile::SOAP::Daemon, XML::Compile::SOAP::WSA, XML::Compile::C14N, XML::Compile::WSS, XML::Compile::Tester, XML::Compile::Cache, XML::Compile::Dumper, XML::Compile::RPC, XML::Rewrite, XML::eXistDB, and XML::LibXML::Simple.

Please post questions or ideas to the mailinglist at http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/xml-compile For live contact with other developers, visit the #xml-compile channel on irc.perl.org.

LICENSE

Copyrights 2011-2012 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html