The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
MARKOV / XML-Compile-WSS-1.03 / lib / XML / Compile / WSS.pod 
=head1 NAME

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

=head1 INHERITANCE

 XML::Compile::WSS is extended by
   XML::Compile::WSS::BasicAuth
   XML::Compile::WSS::Signature
   XML::Compile::WSS::Timestamp

=head1 SYNOPSIS

 # This modules van be used "stand-alone" ...
 my $schema = XML::Compile::Cache->new(...);
 my $auth   = XML::Compile::WSS::BasicAuth->new
   (schema => $schema, username => $user, ...);
 my $elem   = $auth->create($doc, $data);

 # ... or as SOAP slave (strict order of object creation!)
 my $wss    = XML::Compile::SOAP::WSS->new;
 my $wsdl   = XML::Compile::WSDL11->new($wsdlfn);
 my $auth   = $wss->basicAuth(username => $user, ...);
 my $answer = $wsdl->call($operation, wsse_Security => $auth, %data);
 # same, because "all" defined is default
 my $answer = $wsdl->call($operation, %data);
 # or
 my $call   = $wsdl->compileClient($operation);
 my $answer = $call->(%data);

=head1 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 implements features in the C<Security>
header.  One header may contain more than one of these:

=over 4

=item * timestamps in L<XML::Compile::WSS::Timestamp|XML::Compile::WSS::Timestamp>

=item * username/password authentication in L<XML::Compile::WSS::BasicAuth|XML::Compile::WSS::BasicAuth>

=item * signing of the body in L<XML::Compile::WSS::Signature|XML::Compile::WSS::Signature>

=item * encryption is not yet supported.  Please hire me to get it implemented.

=back

You will certainly need the constants from L<XML::Compile::WSS::Util|XML::Compile::WSS::Util>.
Besides, when you want to use Security with SOAP, then use
L<XML::Compile::SOAP::WSS|XML::Compile::SOAP::WSS>.

=head1 METHODS

=head2 Constructors

=over 4

=item XML::Compile::WSS-E<gt>B<new>(OPTIONS)

 -Option     --Default
  schema       undef
  version      undef
  wss_version  <required>

=over 2

=item schema => an L<XML::Compile::Cache|XML::Compile::Cache> object

Add the WSS extension information to the provided schema.  If not used,
you have to call L<loadSchemas()|XML::Compile::WSS/"Internals"> before compiling readers and writers.

=item version => STRING

Alternative for C<wss_version>, but not always as clear.

=item wss_version => '1.1'|MODULE

[1.0] 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 C<::Util>.
The only option is currently C<WSS11MODULE>.

=back

=back

=head2 Attributes

=over 4

=item $obj-E<gt>B<schema>()

=item $obj-E<gt>B<version>()

Returns the version number.

=back

=head2 Apply

=over 4

=item $obj-E<gt>B<check>(SECURITY)

Check whether received SECURITY information is correct.  Each active
WSS feature must check whether it finds information for it.

=item $obj-E<gt>B<create>(DOC, SECURITY, DATA)

Adds some WSS element to SECURITY.  The DATA is the structure which
is passed to some writer (for instance, the DATA which the user
passes to the SOAP call).  There is quite some flexibility in that
structure, so should not be used, in general.

=back

=head2 Helpers

=over 4

=item $obj-E<gt>B<dateTime>(TIME|STRING|HASH)

Returns a structure which can be used as timestamp, for instance in
C<Created> and C<Expires> fields.  This helper function will help you
use these timestamp fields correctly.

The WSU10 specification defines a free format timestamp.  Of course,
that is very impractical.  Typically a "design by committee" decission.
Also, the standard does not describe the ValueType field, which is often
used to cover this design mistake.

example: 

  # Both will get ValueType="$xsd/dateTime"
  Created => time()                 # will get formatted
  Created => '2012-10-14T22:26:21Z' # autodected

  # Explicit formatting
  Created => { _ => 'this Christmas'
             , ValueType => 'http://per6.org/releasedates'
             };

  # No ValueType added
  Created => 'this Christmas'

=back

=head2 Internals

=over 4

=item XML::Compile::WSS-E<gt>B<loadSchemas>(SCHEMA, VERSION)

SCHEMA must extend L<XML::Compile::Cache|XML::Compile::Cache>.

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

=back

=head1 DETAILS

=head2 Specifications

A huge number of specifications act in this field.  Every self respecting
company has contributed its own implementation into the field.  A lot of
this is B<not supported>, but the list of constants should be complete
in L<XML::Compile::WSS::Util|XML::Compile::WSS::Util>.

=over 4

=item * XML Security Generic Hybrid Ciphers

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

=item * XML Signature Properties

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

=item * XML Signature Syntax and Processing Version 1.1

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

=item * SOAP message security

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

=item * XML Signature Syntax and Processing (Second Edition)

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

=item * RFC4050 Using the ECDSA for XML Digital Signatures

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

=item * RFC4051 Additional XML Security Uniform Resource Identifiers (URIs)

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

=item * XML Encryption Syntax and Processing

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

=back

=head1 SEE ALSO

This module is part of XML-Compile-WSS distribution version 1.03,
built on October 26, 2012. Website: F<http://perl.overmeer.net/xml-compile/>

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

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

=head1 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 F<http://www.perl.com/perl/misc/Artistic.html>