=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, ...);

 # ... 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, ...);

=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 supports the following records in
the C<Security> header:

=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>

=back

Encryption is not yet supported.  Please hire me to get it implemented.
You will certainly need the constants from L<XML::Compile::WSS::Util|XML::Compile::WSS::Util>.

=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 => L<XML::Compile::Cache|XML::Compile::Cache>

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 Internals

=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'

=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

=head2 SEE ALSO

=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.00,
built on October 16, 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>

